Skip to main content
Your app is a web page that runs in an iframe, inside a frame Rollout serves, inside the CRM’s contact page. This page covers what that means for how you build it.

Load the app script

Rollout shows your app only after your page says it’s ready, and sizes its frame to the height your page reports. Rollout’s app script does both. Load it on the page your app URL serves:
That’s all most apps need. The script tells Rollout your page has loaded, reports your content’s height, and reports it again whenever it changes. It does nothing when your page is opened outside a frame, so the same page works in a normal browser tab. An app that never says it’s ready stays hidden. If your page fails to load or your server refuses the context, the agent sees nothing rather than an empty or broken box.

Sizing

The frame’s height follows your content, so let your content size itself. A body set to height: 100% or 100vh keeps the frame at whatever height it has rather than following the content. The CRM may set a minimum and maximum height. Past the maximum, your page scrolls inside its frame.
The Easy Cash Offers app in a CRM's Apps tab, showing a traditional sale and a cash offer side by side, each with its costs and net to seller, and Print and Regenerate buttons

The same app after it shows an offer. Its frame grew to fit the new content, with no scroll bar. Rollout shows the app's name above its frame.

When your page reloads

Your page keeps the context it was loaded with. Rollout loads your page again, with a new context, when:
  • the agent opens another contact, so each load is about one contact;
  • the CRM refreshes its apps, for example after the agent turns an app on;
  • your page asks for it, with reload().

Signing agents in

Each load brings a freshly signed context, and that, not a cookie, is how your app knows who’s looking. Browsers may block or partition cookies in a third-party frame, so don’t rely on a session cookie set outside it. The first time an agent opens your app, your server won’t know which of your users they are. One way to handle it:
  1. Your server verifies the context and looks up the agent’s link, (x.marketplaceId, user.id). See Identifying the agent.
  2. If there’s no link, your page shows a Connect button.
  3. The button opens your sign-in page in a popup, with a short-lived, single-use token your server issued for this agent. Don’t sign in inside the frame: Rollout’s frame blocks other origins, such as a sign-in provider, and popups run outside the frame’s sandbox.
  4. Once the agent signs in, your server links them, and the popup tells your frame it’s done, for example with window.opener.postMessage.
  5. Your page calls reload(). Rollout reloads your frame with a fresh context, your server finds the link, and the agent sees your app.
reload() reloads your app’s frame, and only yours, at a freshly signed URL. Use it after anything that should change what your page shows, such as the agent connecting an account in a popup.

Let Rollout frame your page

  • Allow framing. Don’t send X-Frame-Options. If you send a Content-Security-Policy with frame-ancestors, list https://universal.rollout.com, the origin of each CRM page your app shows on, and https://dashboard.universal.rollout.com for previews. Browsers check every ancestor of the frame.
  • Allow Rollout’s script. If your CSP limits script-src, add https://universal.rollout.com.
  • Stay on your origin. Rollout’s frame blocks origins other than the marketplace’s approved apps’ in your frame, and accepts your page’s messages only from your app URL’s origin. A redirect to another domain inside the frame, such as a sign-in provider, won’t show. Use a popup.
Many frameworks block framing by default. Turn it off for your app URL, or set frame-ancestors as above:
The framing policy limits where your page can be shown, but it doesn’t prove a request came from Rollout. The signed context does.

What the iframe allows

Your frame is sandboxed with allow-scripts allow-same-origin allow-forms allow-popups allow-popups-to-escape-sandbox. Open a popup for sign-in and for downloads.

Using Follow Up Boss’s script

An app built for Follow Up Boss can keep FUB’s embeddedApps-v1.0.0.js: the Rollout frame speaks the same protocol. FUB’s script has no reload().

The protocol

If you’d rather not load a script, implement your side of the protocol yourself, with postMessage to window.parent: Rollout accepts these messages only from your frame, and only from your app URL’s origin.