Parent Bridge

This is the low-level postMessage contract between the Phoenix Prediction iframe and your page. Most integrations should use the Host SDK: it implements everything here, including the security checks. Use this page if you cannot add the dependency, are integrating from a non-JS stack, or want to understand exactly what crosses the boundary.

The iframe does not own login, registration, cashier, or deposit. When it needs one of those, it emits an event; your page runs the flow.

Envelope

Every message, in both directions, is one namespaced, versioned object. The receiver's first job is to drop anything that is not a pmm message of version 1.

{
  v: 1,            // protocol version: always 1
  ns: 'pmm',       // namespace: ignore anything else
  kind: 'hello' | 'ready' | 'event' | 'command' | 'reply',
  // the other fields depend on kind (below)
}

Handshake

Once the session first settles, live or refused, the iframe sends hello, and repeats it every 400 ms (8 times in all) until your page answers ready. The iframe sends no other event before its hello; anything that happens first is held and goes out right after it.

// iframe to host
{ v: 1, ns: 'pmm', kind: 'hello', protocolVersion: 1, embedVersion: '...', operator: 'acme',
  capabilities: ['nav.events', 'nav.commands', 'history', 'theme.runtime', 'ticket.open',
                 'action.events', 'wallet.balance', 'language.runtime', 'language.changed',
                 'session.expired'],
  language: 'en',
  views: ['feed', 'listing', 'portfolio', 'leaderboard', 'activity', 'saved'] }

// host to iframe
{ v: 1, ns: 'pmm', kind: 'ready', protocolVersion: 1, capabilities: ['reload.requested'] }

• capabilities in hello lists what this embed supports, so you can check before relying on a feature: language.runtime for setLanguage, language.changed for the language.changed event, session.expired for the session events.
• language is the session's language at the handshake. Each switch after it comes as a language.changed event.
• views lists the views this session offers. A view the operator switched off in Curation, Features (leaderboard, activity) is not in it, so a menu of your own can match what the embed offers (see Your Site's Menu). An embed that predates feature switches sends no views: offer every view then.
• Put reload.requested in your ready capabilities only if your page reloads itself when it receives the reload.requested event. Only then does the "session ended" screen offer a Reload button (see Sessions and Token Refresh).
• After your first ready, the iframe sends a navigation event with its current view.

Events: Iframe to Host

{ v: 1, ns: 'pmm', kind: 'event', name, payload }

Commands: Host to Iframe

{ v: 1, ns: 'pmm', kind: 'command', name, payload }

Commands the iframe does not know are ignored.

Correlated Request (getState)

Send a command with an id; the iframe answers with a reply carrying the same id.

// host to iframe
{ v: 1, ns: 'pmm', kind: 'command', id: 'abc', name: 'getState', payload: {} }
// iframe to host
{ v: 1, ns: 'pmm', kind: 'reply', id: 'abc', ok: true, result: { view: { name: 'feed' }, path: '/' } }

Visitor to Player Flow

1. The iframe starts with a visitor token.
2. The visitor taps Buy and the iframe emits auth.requested.
3. Your site signs the user in; your backend mints a player token.
4. Your page sends a setToken command.
5. The iframe reconnects as the player.

Example Listener

const iframe = document.querySelector('#phoenix-prediction-embed')
const phoenixOrigin = 'https://embed.prediction.phoenixverse.io'

const post = (message) =>
  iframe?.contentWindow?.postMessage({ v: 1, ns: 'pmm', ...message }, phoenixOrigin)
const command = (name, payload) => post({ kind: 'command', name, payload })

window.addEventListener('message', async (event) => {
  // 1) exact origin, 2) only the embed's window, 3) the pmm envelope of our version
  if (event.origin !== phoenixOrigin) return
  if (event.source !== iframe?.contentWindow) return
  const m = event.data
  if (!m || m.ns !== 'pmm' || m.v !== 1) return

  if (m.kind === 'hello') {
    post({ kind: 'ready', protocolVersion: 1, capabilities: ['reload.requested'] })
    return
  }
  if (m.kind !== 'event') return

  switch (m.name) {
    case 'auth.requested':
      command('setToken', { token: await loginAndMintPlayerToken() })
      break
    case 'token.expiring':
    case 'session.expired':
      command('setToken', { token: await mintCurrentSessionToken() })
      break
    case 'reload.requested':
      window.location.reload()
      break
    case 'deposit.requested':
      openCashier()
      break
    case 'resize':
      iframe.style.height = `${m.payload.height}px`
      break
  }
})

Security Requirements

• Check event.origin with exact equality (not startsWith) before trusting any message, and confirm event.source is the embed's contentWindow.
• Send to the exact Phoenix origin, never *.
• Validate the envelope (ns === 'pmm' and v === 1) before reading kind or payload.
• Register allowed origins for each environment (see Allowed Origins). The embed takes the framing page's origin from the browser, sends its events only to a listed origin, ignores commands from any other, and can be framed only by a listed site. Before a session has verified the list (a launch refused at boot), it talks only to the page the browser says is framing it.
• Money truth is server-side. Bridge events coordinate the UI only; never credit, debit, or unlock on a postMessage alone.

Iframe Sandbox and Permissions

If you build the iframe yourself (rather than with the SDK), use these attributes:

<iframe
  src="https://embed.prediction.phoenixverse.io/o/acme?token=JWT"
  sandbox="allow-scripts allow-same-origin allow-popups allow-popups-to-escape-sandbox allow-forms"
  allow="clipboard-write; fullscreen"
  style="width: 100%; min-height: 720px; border: 0"
></iframe>

allow-same-origin is required (the embed needs its own origin for storage and its connection) and is safe because the embed is a different origin from your page. The embed can only be framed by an https page.

Common Questions