At PayPal we write a lot of javascript that ends up running on other websites and other domains. The prime example of this is checkout.js, the integration script for our entire checkout experience, which allows merchants to embed our button and checkout flow seamlessly into their sites.

There are a huge number of perils and pitfalls around running our code on third-party sites, though:

We absolutely can’t break any sites. That means no modifying globals that we didn’t create, including polyfills for browser apis. Doing that causes issues that are virtually impossible to track down, most of the time.

Sites can absolutely break us, and they often do. One recent example of this was a site which overrode Array.prototype.toJSON which in turn broke JSON.stringify . Many sites include a WeakMap polyfill that doesn’t work on cross-domain window objects, like the native version does. So we can’t trust anything we didn’t create or verify first.

which in turn broke . Many sites include a polyfill that doesn’t work on cross-domain window objects, like the native version does. So we can’t trust anything we didn’t create or verify first. Cross domain restrictions (as in what you can and can’t do when you have an iframe or a popup running on a page on a different domain) are incredibly nebulous, and the rules often change depending on which browser you’re in. For example, in IE and Edge, you literally can not send a message between a popup window and a parent window on a different domain, without resorting to soul-crushing hacks.

Some browsers just do really weird things. For instance, to test if a window is same-domain or cross-domain, the only viable approach is to try/catch on accessing or setting a property on the window object. Even with that, Safari insists on logging a cross-origin error to the console — even if the error is caught. This problem used to cause no end of confusion, when our merchants raised bug reports with us only for us to tell them ignore that error.

on accessing or setting a property on the window object. Even with that, Safari insists on logging a cross-origin error to the console — even if the error is caught. This problem used to cause no end of confusion, when our merchants raised bug reports with us only for us to tell them ignore that error. Restrictions that are built to combat invasive advertising often hold back third-party experiences like ours. For example, it’s only possible to open a popup window in the exact instant a user clicks on our button. Do anything asynchronous, and we’ve lost our chance — the browser will block our popup, even though it was technically the result of a user-action. On top of this, restrictions around third-party cookies, designed to prevent ad-tracking, prevent us from being able to persist login sessions in our iframe much of the time.

Last year, we decided to focus on putting together a really solid suite of tools to help avoid these pitfalls, and allow us to create great experiences without constantly having to worry about whether a message would get through, or whether an iframe would successfully render.

We’ve open sourced the whole suite. So, if you’re hoping to build experiences that work on other sites (or maybe even just on different domains in your own organization or company), look no further than here.