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

# Have a Follow Up Boss embedded app? Start here

> Make your Follow Up Boss embedded app run in other CRMs too, from the same codebase.

You've built an embedded app for Follow Up Boss. This guide takes the same app
into every CRM that runs a marketplace on Rollout, while it keeps running in
FUB exactly as it does today.

Rollout's Embedded Apps follow FUB's model, so most of your app carries over:

| Stays the same | Changes |
| - | - |
| Your app is a web page in an iframe, loaded with `context` and `signature` query parameters | You verify with your Rollout client secret |
| The context is base64url JSON, signed with HMAC-SHA256 as hex | The contact's id is in `crm.personId`, not `person.id` |
| FUB's `embeddedApps-v1.0.0.js` script works, and so does its protocol | Ids are strings, and unique only within one marketplace |
| No `X-Frame-Options` header | The context never carries the contact's emails or phone numbers |
| Your app's own UI | Previews are marked with `x.preview`, not `example` and `debugState` |

## How much work it is

That depends on what your app does with the contact:

| If your app… | The work |
| - | - |
| Shows its own data about the contact, stored against FUB's `person.id` | Small. Steps 1 to 4, and 7. |
| Calls FUB's API with `person.id` to read or write the contact | Medium. You'll also call Rollout's Universal API, which mirrors FUB's, instead of FUB's for the other CRMs. Step 6. |
| Finds the contact in your own system by the email or phone in the context | The most. You'll get them from the Universal API instead. Step 5. |

## 1. Tell Rollout launches apart

Both FUB and Rollout load your URL with `context` and `signature`, so your
server needs to know which secret to check against. Rollout keeps any query
parameters in your app URL, so register your app with one that marks it:

```
https://app.example.com/crm-panel?source=rollout
```

Register it in the Rollout dashboard, under **Embedded apps → Apps**. See
[List your app](https://rollout.com/docs/embedded-apps/list-your-app.md) for the other fields. FUB keeps
loading `https://app.example.com/crm-panel` as before.

`source` only picks the secret. It proves nothing on its own: a launch is from
Rollout only if its signature checks out with your Rollout secret.

## 2. Verify with the right secret

This is server-side code, like your FUB check: it needs your secrets, so it
never runs in the browser. It runs when the CRM's frame requests your app URL,
before you render the page.

Keep your FUB check, and add a branch for Rollout launches. Your Rollout client
secret is your **Current secret** on the dashboard's **API** page. Rollout
contexts also carry an expiry and a unique id, so check those too:

```ts Node theme={null}
import { createHmac, timingSafeEqual } from "node:crypto";

function signatureMatches(context: string, signature: string, secret: string) {
  const expected = createHmac("sha256", secret).update(context).digest();
  const actual = Buffer.from(signature, "hex");
  return actual.length === expected.length && timingSafeEqual(actual, expected);
}

export function verifyLaunch(query: Record<string, string | undefined>) {
  const { context, signature, source } = query;
  if (!context || !signature) return null;

  const fromRollout = source === "rollout";
  const secret = fromRollout ? process.env.ROLLOUT_CLIENT_SECRET! : process.env.FUB_SECRET!;
  if (!signatureMatches(context, signature, secret)) return null;

  const decoded = JSON.parse(Buffer.from(context, "base64url").toString("utf8"));

  if (fromRollout) {
    if (decoded.x.exp < Date.now() / 1000) return null; // five-minute expiry
    if (!rememberJti(decoded.x.jti, decoded.x.exp)) return null; // replay check
    return fromRolloutContext(decoded);
  }
  return fromFubContext(decoded);
}
```

```python Python theme={null}
import base64, hashlib, hmac, json, os, time

def signature_matches(context: str, signature: str, secret: str) -> bool:
    expected = hmac.new(secret.encode(), context.encode(), hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected.encode(), signature.encode())

def verify_launch(context: str | None, signature: str | None, source: str | None):
    if not context or not signature:
        return None

    from_rollout = source == "rollout"
    secret = os.environ["ROLLOUT_CLIENT_SECRET" if from_rollout else "FUB_SECRET"]
    if not signature_matches(context, signature, secret):
        return None

    padded = context + "=" * (-len(context) % 4)  # Python's decoder needs the padding
    decoded = json.loads(base64.urlsafe_b64decode(padded))

    if from_rollout:
        if decoded["x"]["exp"] < time.time():  # five-minute expiry
            return None
        if not remember_jti(decoded["x"]["jti"], decoded["x"]["exp"]):  # replay check
            return None
        return from_rollout_context(decoded)
    return from_fub_context(decoded)
```

```ruby Ruby theme={null}
require "base64"
require "json"
require "openssl"

def signature_matches?(context, signature, secret)
  expected = OpenSSL::HMAC.hexdigest("SHA256", secret, context)
  OpenSSL.secure_compare(expected, signature)
end

def verify_launch(context, signature, source)
  return nil if context.to_s.empty? || signature.to_s.empty?

  from_rollout = source == "rollout"
  secret = ENV.fetch(from_rollout ? "ROLLOUT_CLIENT_SECRET" : "FUB_SECRET")
  return nil unless signature_matches?(context, signature, secret)

  decoded = JSON.parse(Base64.urlsafe_decode64(context))

  if from_rollout
    return nil if decoded["x"]["exp"] < Time.now.to_i # five-minute expiry
    return nil unless remember_jti(decoded["x"]["jti"], decoded["x"]["exp"]) # replay check
    return from_rollout_context(decoded)
  end
  from_fub_context(decoded)
end
```

```php PHP theme={null}
function signatureMatches(string $context, string $signature, string $secret): bool
{
    return hash_equals(hash_hmac('sha256', $context, $secret), $signature);
}

function verifyLaunch(?string $context, ?string $signature, ?string $source): ?array
{
    if (!$context || !$signature) {
        return null;
    }

    $fromRollout = $source === 'rollout';
    $secret = getenv($fromRollout ? 'ROLLOUT_CLIENT_SECRET' : 'FUB_SECRET');
    if (!signatureMatches($context, $signature, $secret)) {
        return null;
    }

    $decoded = json_decode(base64_decode(strtr($context, '-_', '+/')), true);

    if ($fromRollout) {
        if ($decoded['x']['exp'] < time()) return null; // five-minute expiry
        if (!rememberJti($decoded['x']['jti'], $decoded['x']['exp'])) return null; // replay check
        return fromRolloutContext($decoded);
    }
    return fromFubContext($decoded);
}
```

```go Go theme={null}
import (
	"crypto/hmac"
	"crypto/sha256"
	"encoding/base64"
	"encoding/hex"
	"encoding/json"
	"os"
	"time"
)

// verifyLaunch returns the decoded context, or nil if the launch doesn't check out.
func verifyLaunch(context, signature, source string) map[string]any {
	if context == "" || signature == "" {
		return nil
	}

	fromRollout := source == "rollout"
	secret := os.Getenv("FUB_SECRET")
	if fromRollout {
		secret = os.Getenv("ROLLOUT_CLIENT_SECRET")
	}

	mac := hmac.New(sha256.New, []byte(secret))
	mac.Write([]byte(context))
	actual, err := hex.DecodeString(signature)
	if err != nil || !hmac.Equal(actual, mac.Sum(nil)) {
		return nil
	}

	raw, err := base64.RawURLEncoding.DecodeString(context)
	if err != nil {
		return nil
	}
	var decoded map[string]any
	if json.Unmarshal(raw, &decoded) != nil {
		return nil
	}

	if fromRollout {
		x, _ := decoded["x"].(map[string]any)
		exp, _ := x["exp"].(float64)
		jti, _ := x["jti"].(string)
		if int64(exp) < time.Now().Unix() { // five-minute expiry
			return nil
		}
		if !rememberJti(jti, int64(exp)) { // replay check
			return nil
		}
	}
	return decoded // then map it, as in step 3
}
```

```java Java theme={null}
import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;
import java.nio.charset.StandardCharsets;
import java.security.MessageDigest;
import java.time.Instant;
import java.util.Base64;
import java.util.HexFormat;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;

public class LaunchVerifier {
  private static final ObjectMapper JSON = new ObjectMapper();

  /** The decoded context, or null if the launch doesn't check out. */
  public static JsonNode verifyLaunch(String context, String signature, String source)
      throws Exception {
    if (context == null || context.isEmpty() || signature == null || signature.isEmpty()) {
      return null;
    }

    boolean fromRollout = "rollout".equals(source);
    String secret = System.getenv(fromRollout ? "ROLLOUT_CLIENT_SECRET" : "FUB_SECRET");

    Mac mac = Mac.getInstance("HmacSHA256");
    mac.init(new SecretKeySpec(secret.getBytes(StandardCharsets.UTF_8), "HmacSHA256"));
    byte[] expected = mac.doFinal(context.getBytes(StandardCharsets.UTF_8));
    byte[] actual;
    try {
      actual = HexFormat.of().parseHex(signature);
    } catch (IllegalArgumentException e) {
      return null;
    }
    if (!MessageDigest.isEqual(expected, actual)) {
      return null;
    }

    JsonNode decoded = JSON.readTree(Base64.getUrlDecoder().decode(context));

    if (fromRollout) {
      long exp = decoded.path("x").path("exp").asLong();
      if (exp < Instant.now().getEpochSecond()) return null; // five-minute expiry
      if (!rememberJti(decoded.path("x").path("jti").asText(), exp)) return null; // replay check
    }
    return decoded; // then map it, as in step 3
  }
}
```

```csharp C# theme={null}
using System.Security.Cryptography;
using System.Text;
using System.Text.Json;

public static class LaunchVerifier
{
    /// <summary>The decoded context, or null if the launch doesn't check out.</summary>
    public static JsonElement? VerifyLaunch(string? context, string? signature, string? source)
    {
        if (string.IsNullOrEmpty(context) || string.IsNullOrEmpty(signature)) return null;

        var fromRollout = source == "rollout";
        var secret = Environment.GetEnvironmentVariable(
            fromRollout ? "ROLLOUT_CLIENT_SECRET" : "FUB_SECRET")!;

        var expected = HMACSHA256.HashData(
            Encoding.UTF8.GetBytes(secret), Encoding.UTF8.GetBytes(context));
        byte[] actual;
        try { actual = Convert.FromHexString(signature); }
        catch (FormatException) { return null; }
        if (!CryptographicOperations.FixedTimeEquals(expected, actual)) return null;

        var base64 = context.Replace('-', '+').Replace('_', '/');
        base64 = base64.PadRight(base64.Length + (4 - base64.Length % 4) % 4, '=');
        var decoded = JsonDocument.Parse(Convert.FromBase64String(base64)).RootElement;

        if (fromRollout)
        {
            var x = decoded.GetProperty("x");
            var exp = x.GetProperty("exp").GetInt64();
            if (exp < DateTimeOffset.UtcNow.ToUnixTimeSeconds()) return null; // five-minute expiry
            if (!RememberJti(x.GetProperty("jti").GetString()!, exp)) return null; // replay check
        }
        return decoded; // then map it, as in step 3
    }
}
```

Call it from the route that serves your app URL, and render the page only
for a launch that checks out:

```ts Express theme={null}
app.get("/crm-panel", (req, res) => {
  const launch = verifyLaunch(req.query as Record<string, string>);
  if (!launch) return res.status(401).send("This link is invalid or has expired.");
  res.send(renderPanel(launch)); // your page, with the app script
});
```

```python Flask theme={null}
from flask import Flask, request

app = Flask(__name__)

@app.get("/crm-panel")
def crm_panel():
    args = request.args
    launch = verify_launch(args.get("context"), args.get("signature"), args.get("source"))
    if not launch:
        return "This link is invalid or has expired.", 401
    return render_panel(launch)  # your page, with the app script
```

```ruby Rails theme={null}
class CrmPanelController < ApplicationController
  def show
    launch = verify_launch(params[:context], params[:signature], params[:source])
    return render(plain: "This link is invalid or has expired.", status: :unauthorized) unless launch

    render :show, locals: { launch: launch } # your page, with the app script
  end
end
```

```php PHP theme={null}
// crm-panel.php

$launch = verifyLaunch($_GET['context'] ?? null, $_GET['signature'] ?? null, $_GET['source'] ?? null);
if (!$launch) {
    http_response_code(401);
    exit('This link is invalid or has expired.');
}
renderPanel($launch); // your page, with the app script
```

```go Go theme={null}
http.HandleFunc("GET /crm-panel", func(w http.ResponseWriter, r *http.Request) {
	q := r.URL.Query()
	launch := verifyLaunch(q.Get("context"), q.Get("signature"), q.Get("source"))
	if launch == nil {
		http.Error(w, "This link is invalid or has expired.", http.StatusUnauthorized)
		return
	}
	renderPanel(w, launch) // your page, with the app script
})
```

```java Spring theme={null}
@GetMapping("/crm-panel")
public ResponseEntity<String> crmPanel(
    @RequestParam(required = false) String context,
    @RequestParam(required = false) String signature,
    @RequestParam(required = false) String source) throws Exception {
  JsonNode launch = LaunchVerifier.verifyLaunch(context, signature, source);
  if (launch == null) {
    return ResponseEntity.status(401).body("This link is invalid or has expired.");
  }
  return ResponseEntity.ok(renderPanel(launch)); // your page, with the app script
}
```

```csharp ASP.NET Core theme={null}
app.MapGet("/crm-panel", (string? context, string? signature, string? source) =>
{
    var launch = LaunchVerifier.VerifyLaunch(context, signature, source);
    return launch is null
        ? Results.Text("This link is invalid or has expired.", statusCode: 401)
        : Results.Content(RenderPanel(launch.Value), "text/html"); // your page, with the app script
});
```

In Go, Java and C#, `verifyLaunch` returns the decoded context, and you map it
as in step 3. `rememberJti` is yours to write: it stores each id until its
expiry, and fails on one it's seen. See
[Verify the context](https://rollout.com/docs/embedded-apps/verify-the-context.md) for the details.

## 3. Map both contexts to one shape

Your app's code shouldn't care which CRM it's in. Turn each context into one
shape of your own, and use only that from here on:

```ts Node theme={null}
type Launch = {
  source: "fub" | "rollout";
  /** Whose workspace this is: a FUB account, or an org in one CRM. */
  workspaceKey: string;
  /** The agent looking at the contact. */
  agentKey: string;
  /** The contact on screen. */
  contactKey: string;
  /** The CRM's own id for the contact, to show or send back to the CRM. */
  crmContactId: string;
  firstName?: string;
  lastName?: string;
  stageName?: string;
  /** From FUB's context, or from the Universal API (step 5). */
  emails: string[];
  phones: string[];
  /** The contact's Universal API id, when Rollout sends one (step 5). */
  universalPersonId?: string;
  preview: boolean;
};

function fromFubContext(ctx: any): Launch {
  const account = `fub:${ctx.account.id}`;
  return {
    source: "fub",
    workspaceKey: account,
    agentKey: `${account}:user:${ctx.user.id}`,
    contactKey: `${account}:person:${ctx.person.id}`,
    crmContactId: String(ctx.person.id),
    firstName: ctx.person.firstName,
    lastName: ctx.person.lastName,
    stageName: ctx.person.stage?.name,
    emails: (ctx.person.emails ?? []).map((e: any) => e.value),
    phones: (ctx.person.phones ?? []).map((p: any) => p.value),
    preview: ctx.example === true,
  };
}

function fromRolloutContext(ctx: any): Launch {
  const marketplace = `rollout:${ctx.x.marketplaceId}`;
  const agentKey = `${marketplace}:user:${ctx.user.id}`;
  return {
    source: "rollout",
    workspaceKey: ctx.org ? `${marketplace}:org:${ctx.org.id}` : agentKey,
    agentKey,
    contactKey: `${marketplace}:person:${ctx.crm.personId}`,
    crmContactId: ctx.crm.personId,
    firstName: ctx.person?.firstName,
    lastName: ctx.person?.lastName,
    stageName: ctx.person?.stage?.name,
    emails: [],
    phones: [],
    universalPersonId: ctx.person?.id,
    preview: ctx.x.preview === true,
  };
}
```

```python Python theme={null}
def from_fub_context(ctx: dict) -> dict:
    account = f"fub:{ctx['account']['id']}"
    person = ctx["person"]
    return {
        "source": "fub",
        "workspace_key": account,
        "agent_key": f"{account}:user:{ctx['user']['id']}",
        "contact_key": f"{account}:person:{person['id']}",
        "crm_contact_id": str(person["id"]),
        "first_name": person.get("firstName"),
        "last_name": person.get("lastName"),
        "stage_name": (person.get("stage") or {}).get("name"),
        "emails": [e["value"] for e in person.get("emails", [])],
        "phones": [p["value"] for p in person.get("phones", [])],
        "preview": ctx.get("example") is True,
    }

def from_rollout_context(ctx: dict) -> dict:
    marketplace = f"rollout:{ctx['x']['marketplaceId']}"
    agent_key = f"{marketplace}:user:{ctx['user']['id']}"
    person = ctx.get("person") or {}
    return {
        "source": "rollout",
        "workspace_key": f"{marketplace}:org:{ctx['org']['id']}" if ctx.get("org") else agent_key,
        "agent_key": agent_key,
        "contact_key": f"{marketplace}:person:{ctx['crm']['personId']}",
        "crm_contact_id": ctx["crm"]["personId"],
        "first_name": person.get("firstName"),
        "last_name": person.get("lastName"),
        "stage_name": (person.get("stage") or {}).get("name"),
        "emails": [],
        "phones": [],
        "universal_person_id": person.get("id"),
        "preview": ctx["x"].get("preview") is True,
    }
```

```ruby Ruby theme={null}
def from_fub_context(ctx)
  account = "fub:#{ctx["account"]["id"]}"
  person = ctx["person"]
  {
    source: "fub",
    workspace_key: account,
    agent_key: "#{account}:user:#{ctx["user"]["id"]}",
    contact_key: "#{account}:person:#{person["id"]}",
    crm_contact_id: person["id"].to_s,
    first_name: person["firstName"],
    last_name: person["lastName"],
    stage_name: person.dig("stage", "name"),
    emails: (person["emails"] || []).map { |e| e["value"] },
    phones: (person["phones"] || []).map { |p| p["value"] },
    preview: ctx["example"] == true,
  }
end

def from_rollout_context(ctx)
  marketplace = "rollout:#{ctx["x"]["marketplaceId"]}"
  agent_key = "#{marketplace}:user:#{ctx["user"]["id"]}"
  person = ctx["person"] || {}
  {
    source: "rollout",
    workspace_key: ctx["org"] ? "#{marketplace}:org:#{ctx["org"]["id"]}" : agent_key,
    agent_key: agent_key,
    contact_key: "#{marketplace}:person:#{ctx["crm"]["personId"]}",
    crm_contact_id: ctx["crm"]["personId"],
    first_name: person["firstName"],
    last_name: person["lastName"],
    stage_name: person.dig("stage", "name"),
    emails: [],
    phones: [],
    universal_person_id: person["id"],
    preview: ctx["x"]["preview"] == true,
  }
end
```

```php PHP theme={null}
function fromFubContext(array $ctx): array
{
    $account = "fub:{$ctx['account']['id']}";
    $person = $ctx['person'];
    return [
        'source' => 'fub',
        'workspaceKey' => $account,
        'agentKey' => "$account:user:{$ctx['user']['id']}",
        'contactKey' => "$account:person:{$person['id']}",
        'crmContactId' => (string) $person['id'],
        'firstName' => $person['firstName'] ?? null,
        'lastName' => $person['lastName'] ?? null,
        'stageName' => $person['stage']['name'] ?? null,
        'emails' => array_column($person['emails'] ?? [], 'value'),
        'phones' => array_column($person['phones'] ?? [], 'value'),
        'preview' => ($ctx['example'] ?? false) === true,
    ];
}

function fromRolloutContext(array $ctx): array
{
    $marketplace = "rollout:{$ctx['x']['marketplaceId']}";
    $agentKey = "$marketplace:user:{$ctx['user']['id']}";
    $person = $ctx['person'] ?? [];
    return [
        'source' => 'rollout',
        'workspaceKey' => isset($ctx['org']) ? "$marketplace:org:{$ctx['org']['id']}" : $agentKey,
        'agentKey' => $agentKey,
        'contactKey' => "$marketplace:person:{$ctx['crm']['personId']}",
        'crmContactId' => $ctx['crm']['personId'],
        'firstName' => $person['firstName'] ?? null,
        'lastName' => $person['lastName'] ?? null,
        'stageName' => $person['stage']['name'] ?? null,
        'emails' => [],
        'phones' => [],
        'universalPersonId' => $person['id'] ?? null,
        'preview' => ($ctx['x']['preview'] ?? false) === true,
    ];
}
```

In Go, Java or C#, do the same with a struct or record of your own, and your
JSON library's lookups.

A few things the mapping takes care of:

* **The contact's id.** FUB's `person.id` is the contact's id in FUB. In a
  Rollout context, the CRM's id for the contact is `crm.personId`. `person.id`
  is something else: the contact's Universal API id, sent only in the case
  step 5 describes.
* **The workspace.** FUB sends `account.id`. Rollout sends no account id: use
  `org.id`, the CRM's id for the agent's office, team or site, when the CRM
  sends one, and the agent otherwise.
* **Ids.** FUB's ids are numbers, unique across FUB. Rollout's are strings,
  each CRM's own, and unique only within one marketplace: two CRMs can both
  have a contact `1234`. Every key above includes `x.marketplaceId`.
* **Previews.** FUB marks a preview with `example: true` and a `debugState`.
  Rollout marks one with `x.preview: true`, and sends a made-up agent and
  contact. There are no debug states. See
  [Previews](https://rollout.com/docs/embedded-apps/verify-the-context.md#previews).

The context fields are all listed in [Context fields](https://rollout.com/docs/embedded-apps/context-fields.md).

## 4. Key your stored data by source

If your tables store FUB's ids as they are, a contact `1234` from another CRM
would collide with FUB's contact `1234`. Store the keys from step 3 instead, or
add a source column:

```sql theme={null}
alter table contact_notes add column source text not null default 'fub';
alter table contact_notes add column marketplace_id text; -- null for FUB rows
```

Do the same wherever you link a CRM user to your own user. FUB apps often match
the agent through FUB's account and user ids. For Rollout launches, link
`agentKey`, which holds the marketplace and `user.id`, to your user the first
time the agent signs in. See [Signing agents in](https://rollout.com/docs/embedded-apps/build-the-page.md#signing-agents-in).

## 5. Get the contact's emails and phones

FUB puts the contact's emails and phones in the context. Rollout never does.
If your app needs them, read them from Rollout's
[Universal API](https://rollout.com/docs/embedded-apps/read-crm-data.md):

1. Ask Rollout to turn on the Universal API for your account, if it isn't
   already.
2. Have each agent connect their CRM account to your app through
   [Rollout Link](https://rollout.com/docs/getting-started/show-the-authentication-ui.md). This is a
   one-time step, in your app's settings or in a popup from your embedded app.
3. Once their CRM has synced, every launch for that agent carries the
   contact's Universal API id as `person.id`. Fetch the contact with it:

```ts Node theme={null}
async function contactDetails(launch: Launch, authToken: string, credentialId: string) {
  if (!launch.universalPersonId) return launch; // not connected, or not synced yet

  const res = await fetch(
    `https://crm.universal.rollout.com/api/people/${launch.universalPersonId}`,
    { headers: { Authorization: `Bearer ${authToken}`, "x-rollout-credential-id": credentialId } },
  );
  if (!res.ok) return launch;

  const person = await res.json();
  return {
    ...launch,
    emails: (person.emails ?? []).map((e: { value: string }) => e.value),
    phones: (person.phones ?? []).map((p: { value: string }) => p.value),
  };
}
```

```python Python theme={null}
import requests

def contact_details(launch: dict, auth_token: str, credential_id: str) -> dict:
    if not launch.get("universal_person_id"):
        return launch  # not connected, or not synced yet

    res = requests.get(
        f"https://crm.universal.rollout.com/api/people/{launch['universal_person_id']}",
        headers={"Authorization": f"Bearer {auth_token}", "x-rollout-credential-id": credential_id},
        timeout=10,
    )
    if not res.ok:
        return launch

    person = res.json()
    return {
        **launch,
        "emails": [e["value"] for e in person.get("emails", [])],
        "phones": [p["value"] for p in person.get("phones", [])],
    }
```

```ruby Ruby theme={null}
require "json"
require "net/http"

def contact_details(launch, auth_token, credential_id)
  return launch unless launch[:universal_person_id] # not connected, or not synced yet

  uri = URI("https://crm.universal.rollout.com/api/people/#{launch[:universal_person_id]}")
  req = Net::HTTP::Get.new(uri)
  req["Authorization"] = "Bearer #{auth_token}"
  req["x-rollout-credential-id"] = credential_id
  res = Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https") { |http| http.request(req) }
  return launch unless res.is_a?(Net::HTTPSuccess)

  person = JSON.parse(res.body)
  launch.merge(
    emails: (person["emails"] || []).map { |e| e["value"] },
    phones: (person["phones"] || []).map { |p| p["value"] },
  )
end
```

```php PHP theme={null}
function contactDetails(array $launch, string $authToken, string $credentialId): array
{
    if (empty($launch['universalPersonId'])) {
        return $launch; // not connected, or not synced yet
    }

    $ch = curl_init('https://crm.universal.rollout.com/api/people/' . rawurlencode($launch['universalPersonId']));
    curl_setopt_array($ch, [
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_TIMEOUT => 10,
        CURLOPT_HTTPHEADER => ["Authorization: Bearer $authToken", "x-rollout-credential-id: $credentialId"],
    ]);
    $body = curl_exec($ch);
    if (curl_getinfo($ch, CURLINFO_HTTP_CODE) !== 200) {
        return $launch;
    }

    $person = json_decode($body, true);
    return [
        ...$launch,
        'emails' => array_column($person['emails'] ?? [], 'value'),
        'phones' => array_column($person['phones'] ?? [], 'value'),
    ];
}
```

The Universal API's `emails` and `phones` have the same shape as FUB's
context: `value`, `type`, `status` and `isPrimary`, so code that reads FUB's
can read these.

Rollout sends `person.id` only when the agent's connection is live, has synced
the contact, and the CRM's connector can match the contact's id. A contact
created moments ago may not have one until the next sync. Until then, show what
you can without the email or phone, or ask the agent to connect.

If you can't use the Universal API, build the Rollout side of your app around
`crmContactId`: store your data against it, and ask the agent for an email or
phone when your app needs one.

## 6. Read and write the CRM through the Universal API

If your app calls FUB's API, for example to add a note or read the contact's
tasks, keep calling it for FUB launches. For Rollout launches, call the
Universal CRM API instead, with the credential the agent connected in step 5.
It mirrors FUB's API: the same resources, payloads and responses for people,
notes, tasks and more, whichever CRM the agent uses.

[Have a Follow Up Boss integration? Start here](https://rollout.com/docs/getting-started/have-a-follow-up-boss-integration-start-here.md)
shows how to route those calls by CRM. Don't write to a CRM on a preview.

## 7. Let Rollout frame your page

Your page now also loads in a frame Rollout serves, inside the CRM's page.

* **Framing.** You already send no `X-Frame-Options`, as FUB requires. If you
  send a `Content-Security-Policy` with `frame-ancestors`, add
  `https://universal.rollout.com`, the origin of each CRM page your app shows
  on, and `https://dashboard.universal.rollout.com` for previews. If you serve
  the Rollout URL from a new route, check that your framework doesn't add
  `X-Frame-Options` to it. See
  [Let Rollout frame your page](https://rollout.com/docs/embedded-apps/build-the-page.md#let-rollout-frame-your-page).
* **The script.** FUB's `embeddedApps-v1.0.0.js` works as is. Rollout's
  `https://universal.rollout.com/api/embedded-apps/app-v1.js` does the same,
  and adds `reload()`, which reloads your frame with a fresh context, for
  example after the agent connects their CRM in a popup. If your CSP limits
  `script-src`, allow the one you load.
* **Downloads.** FUB's iframe allows downloads. Rollout's doesn't: open a popup
  for them.

See [Build the page](https://rollout.com/docs/embedded-apps/build-the-page.md) for sizing, sign-in and
the iframe's limits.

## 8. Test and list

1. On your app's page under **Embedded apps → Apps**, choose **Test the
   signature check**. Open the signed sample, and check that your app takes the
   Rollout branch and shows a preview.
2. Submit your app to CRMs' marketplaces from **Embedded apps → Marketplaces**.
   Each CRM reviews it in a preview, so show sample data there, not a sign-in
   screen. See [List your app](https://rollout.com/docs/embedded-apps/list-your-app.md).

## Field by field

| Follow Up Boss | Rollout | Notes |
| - | - | - |
| `context` | `context` | Always `"person"`. |
| `account.id` | — | Use `org.id`, or the agent when there's none. |
| `account.domain`, `account.owner` | `account.domain`, `account.owner` | Optional. |
| `user.id` | `user.id` | The CRM's id for the agent. A string. |
| `user.name`, `user.email` | `user.name`, `user.email` | Optional. |
| `person.id` | `crm.personId` | The CRM's id for the contact. A string. |
| — | `person.id` | The contact's Universal API id, when Rollout can send it. |
| `person.firstName`, `person.lastName` | `person.firstName`, `person.lastName` | Optional. |
| `person.stage` | `person.stage` | Optional. Its `id` is a string. |
| `person.emails`, `person.phones` | — | Read them from the Universal API. |
| `example`, `debugState` | `x.preview` | Previews only. |
| — | `crm.accountId`, `org.id` | The CRM's id for the agent's org. |
| — | `x.platform` | Which CRM, such as `cinc`. |
| — | `x.marketplaceId` | Which marketplace. Part of every stored key. |
| — | `x.appId` | Your app's id in Rollout. |
| — | `x.iat`, `x.exp`, `x.jti` | When it was signed, when it expires, and its id for replay checks. |


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