PostMessage protocol

When embedding via iframe, the host and CDP communicate with postMessage. Using bindPostMessageHost from @segmentify/common implements this protocol for you; this page documents the wire format in case you integrate manually.

All messages are plain objects: { type: string, version?: '1', payload?: unknown }.

When using bindPostMessageHost, the helper wraps init data in the correct envelope. If you implement the protocol manually, send SEGMENTIFY_HOST_INIT like this:

iframe.contentWindow?.postMessage(
  {
    type: "SEGMENTIFY_HOST_INIT",
    version: "1",
    payload: {
      version: "1",
      environment: "production",
      hostBaseUrl: "https://sauron.segmentify.com",
      cdpBaseUrl: "https://api.segmentify.com",
      authToken: bearerToken,
      hostData: accountContext,
      requestHeaders: { "X-Switch-User": "…", "X-Switch-Region": "ALL" },
    },
  },
  "https://cdp.segmentify.com"
);

The init fields live inside payload, not at the top level of the message.

Message types

Type	Direction	Purpose
SEGMENTIFY_MFE_READY	iframe → parent	MFE loaded, waiting for init
SEGMENTIFY_HOST_INIT	parent → iframe	Initial config (required)
SEGMENTIFY_HOST_DATA_UPDATE	parent → iframe	Account context update
SEGMENTIFY_HOST_AUTH_UPDATE	parent → iframe	Auth token refresh
SEGMENTIFY_MFE_NAVIGATE	iframe → parent	Request parent navigation
SEGMENTIFY_MFE_ERROR	iframe → parent	Fatal error reporting

SEGMENTIFY_HOST_INIT payload

{
  version: "1";
  environment: "development" | "qa" | "production";
  hostBaseUrl: string;       // Sauron API (host)
  cdpBaseUrl?: string;       // CDP API — required for the CDP MFE
  authToken?: string;        // Bearer token for API calls
  hostData?: HostData;       // account context (apiKey, currency, …)
  requestHeaders?: Record<string, string>; // e.g. X-Switch-User, X-Switch-Region
}

HostData shape (minimum for API calls)

{
  user?: {
    user?: {
      account?: {
        apiKey?: string;
        dataCenter?: "eq" | "gc" | string;
        mainCurrency?: { code?: string; symbol?: string };
      };
      lang?: string;
      privileges?: string[];
    };
  };
  switchedUser?: { /* optional multi-account */ };
  switchRegion?: { selectedRegion?: string };
}

CDP HTTP routing

Client	Base URL	Notes
cdpApi	cdpBaseUrl	Adds X-Api-Version: 1.0 automatically

cdpBaseUrl is required for the CDP MFE. Switch headers (X-Switch-User, X-Switch-Region) must be provided by the host via requestHeaders.

Handshake ordering

1. Parent creates the iframe pointing at embed.html.
2. CDP boots and posts SEGMENTIFY_MFE_READY.
3. Parent responds with SEGMENTIFY_HOST_INIT.
4. Parent may later send SEGMENTIFY_HOST_DATA_UPDATE / SEGMENTIFY_HOST_AUTH_UPDATE.
5. CDP posts SEGMENTIFY_MFE_NAVIGATE when it wants the parent to change route.

Manual origin validation

If you handle messages yourself, validate the origin and source. @segmentify/common exports a helper:

import { isTrustedPostMessageEvent } from "@segmentify/common";

window.addEventListener("message", (event) => {
  if (!isTrustedPostMessageEvent(event, iframe.contentWindow, "https://cdp.segmentify.com")) {
    return;
  }
  // handle event.data
});