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

# How it works

> The pieces of the marketplace, who runs each, and what happens when an agent opens a contact.

## Three parties

| | Who | What they do |
| - | - | - |
| **You**, the marketplace owner | A CRM, or any product with records its users work on | Mount Rollout's components on your pages, sign a token for each user, and review the apps listed in your marketplace. |
| **App publishers** | Companies that build apps for real estate agents | Register their apps with Rollout, list them in your marketplace, and check the context Rollout signs for each launch. |
| **Rollout** | | Runs the frame apps load in, signs every launch, onboards publishers, and keeps track of who has which app on. |

Apps never talk to you directly, and you never hold a publisher's secret.

## What happens when an agent opens a contact

```mermaid theme={null}
sequenceDiagram
  actor Agent
  participant Page as Your contact page
  participant Server as Your server
  participant Rollout
  participant App as Publisher's app
  Agent->>Page: Opens a contact
  Page->>Server: Token for this agent and contact?
  Server-->>Page: Short-lived user token, signed with your secret
  Page->>Rollout: Loads the Rollout frame with the token and the contact
  Rollout->>Rollout: Finds the apps this agent or their org turned on,<br/>and signs a context for each
  Rollout->>App: Loads each app in its own frame,<br/>with its signed context
  App->>App: Checks the signature
  App-->>Rollout: Ready, and how tall it is
  Rollout-->>Agent: Shows the app on the contact
```

1. Your page asks **your server** for a token. Your server signs a short-lived
   **user token** for the agent signed in to your CRM, with your Rollout client
   secret. It names the agent, their org, and the contact on screen.
2. `mountEmbeddedApps()` loads the **Rollout frame** from Rollout's origin, and
   hands it the token and the contact.
3. Rollout finds the apps the agent, or their org, turned on. For each one, it
   signs a **context** with that app's publisher's secret: who is looking, at
   which contact, in which marketplace.
4. The Rollout frame loads each app in its own sandboxed **app frame**, with
   its context in the URL. The app checks the signature, tells Rollout it's
   ready, and is shown, sized to its content.

The marketplace works the same way: your page asks your server for a token that
lets the user turn apps on, and `mountEmbeddedAppMarketplace()` lists your
approved apps and saves each switch with Rollout.

## How the pieces fit

```mermaid theme={null}
flowchart LR
  subgraph CRM["Your pages (the host page)"]
    C1["mountEmbeddedApps()"]
    C2["mountEmbeddedAppMarketplace()<br/>or your own switches"]
  end
  subgraph Rollout["universal.rollout.com"]
    F["Rollout frame"]
    L["Launch endpoint"]
    M["Marketplace routes"]
  end
  subgraph Apps["App publishers' pages"]
    A1["App frame: App A"]
    A2["App frame: App B"]
  end
  S["Your server"] -- "user token" --> CRM
  C1 -- "iframe" --> F
  F -- "token + contact" --> L
  L -- "signed app URLs" --> F
  F -- "iframe, ?context=…&signature=…" --> A1
  F -- "iframe" --> A2
  C2 -- "list apps, turn on/off" --> M
```

The signed contexts and the apps' traffic stay inside the Rollout frame, out of
reach of your page's scripts.

## How an app gets into your marketplace

An app reaches your users only after its publisher lists it and you approve
it:

```mermaid theme={null}
stateDiagram-v2
  [*] --> pending: Publisher lists the app
  pending --> approved: You approve
  pending --> rejected: You reject, with a note
  pending --> withdrawn: Publisher withdraws
  approved --> suspended: You suspend, with a note
  suspended --> approved: You reinstate
  approved --> withdrawn: Publisher withdraws
  approved --> pending: Publisher changes the app URL
  suspended --> pending: Publisher changes the app URL
  rejected --> pending: Publisher lists it again
  withdrawn --> pending: Publisher lists it again
```

Users see an app only while its listing is **approved** and its publisher's
account is active. Suspending or withdrawing a listing hides it, but keeps every
user's and org's choice to turn it on, so reinstating or re-approving it
restores them all.

## Compatible with Follow Up Boss apps

The marketplace follows Follow Up Boss's embedded apps model: the same
`context` and `signature` parameters, the same signing, and the same protocol
for showing and sizing an app. A publisher with an app for FUB keeps its
signature check and FUB's script, and changes the fields it reads. The
[Follow Up Boss guide](https://rollout.com/docs/embedded-apps/coming-from-follow-up-boss)
takes publishers through it.

## Current limits

* Apps show on **person** (contact) records only.
* Rollout sets up marketplace owners and app publishers. Contact Rollout to get
  started.
* Marketplaces are public or invite-only, but invites can't be sent yet. An
  invite-only marketplace is hidden from every publisher not already listed in
  it.
* An app has one URL for every marketplace. There is no versioning, no per-app
  secret and no sandbox marketplace yet.
* No emails are sent when an app is listed or reviewed. Check the dashboard.

## Glossary

| Term | Meaning |
| - | - |
| Marketplace owner | The CRM that owns a marketplace. You. |
| App publisher | The company that builds and lists an app. |
| Host page | Your page that mounts Rollout's components. |
| Rollout frame | The page Rollout serves inside your page, which loads each app. |
| App frame | The iframe one app renders in, inside the Rollout frame. |
| User token | The JWT your server signs for a user, which Rollout's components use. |
| Context | The signed JSON document an app receives in its URL: the viewer, the contact and the marketplace. |
| Listing | One app in one marketplace, with its review status. |
| Enablement | A user's, or an org's, choice to turn an app on. |
| Enablement scope | Who an enablement is for: `user`, the user alone, or `org`, everyone in the user's org. |
| Token scope | What a user token allows: `embed:render`, `embed:enable` or `embed:enable_org`. |

## Next

The [implementation plan](https://embedded-apps.rollout.com/build/overview.md) takes you from first call to a live
marketplace.


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