> ## Documentation Index
> Fetch the complete documentation index at: https://rollout.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Build the page

> Load Rollout's app script, size your content, sign agents in, and work within the iframe.

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:

```html theme={null}
<script type="module" src="https://universal.rollout.com/api/embedded-apps/app-v1.js"></script>
```

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](https://mintcdn.com/rollout/l0jLuVTIfNu5jYvw/images/embedded-apps/app-in-apps-tab.png?fit=max\&auto=format\&n=l0jLuVTIfNu5jYvw\&q=85\&s=cde4eda9eef64953793dcb855d0c8e33)

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](https://rollout.com/docs/embedded-apps/context-fields.md#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.

```js theme={null}
import { reload } from "https://universal.rollout.com/api/embedded-apps/app-v1.js";

window.addEventListener("message", (event) => {
  if (event.origin === "https://app.example.com" && event.data === "signed-in") {
    reload();
  }
});
```

`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.

> [!WARNING]
>
> Many frameworks block framing by default. Turn it off for your app URL, or set
> `frame-ancestors` as above:
>
> | Framework | Default | Turn it off |
> | - | - | - |
> | Express with `helmet` | `X-Frame-Options: SAMEORIGIN` and `frame-ancestors 'self'` | Set `frameguard: false`, and your own `frameAncestors` |
> | Rails | `X-Frame-Options: SAMEORIGIN` | Remove `X-Frame-Options` from `config.action_dispatch.default_headers`, or delete the header in the controller |
> | Django | `X-Frame-Options: DENY`, from `XFrameOptionsMiddleware` | Decorate the view with `@xframe_options_exempt` |
> | Spring Security | `X-Frame-Options: DENY` | `http.headers(h -> h.frameOptions(f -> f.disable()))` |

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`.

| Your page can | Your page can't |
| - | - |
| Run scripts | Navigate the CRM's page |
| Keep its own storage, which browsers may partition | Show `alert`, `confirm` or `prompt` dialogs |
| Submit forms | Start downloads in the frame |
| Open popups, which run unsandboxed | Load another site's pages in the frame |

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`:

| Direction | Message | When |
| - | - | - |
| Rollout → app | `{ action: "STATUS", id }` | Each time your page loads in the frame. |
| App → Rollout | `{ action: "STATUS", status: "LOADED", id }` | In answer. Post it to the origin the STATUS came from, echoing its `id`. Your frame is shown on this. |
| App → Rollout | `{ action: "HEIGHT", height, id }` | After LOADED, and whenever your content's height changes, in px. |
| App → Rollout | `{ action: "rollout:reload", id }` | To get a freshly signed context. Rollout only. |

Rollout accepts these messages only from your frame, and only from your app
URL's origin.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.