Skip to main content

Handshake

Child-initiated, with a host-initiated fallback.

1. Host mounts the iframe with ?embed=1&host={origin}
2. Map posts   map.ready      { protocol: 1, campus, capabilities[], build? }
3. Host sends  host.hello     { sdk, protocol }                        optional
   Map answers                { protocol: 1, campus, capabilities[], build? }
4. Map posts   map.loaded     { ...state }                             once bundles resolve

Steps 2 and 3 carry the same payload; either is sufficient to connect. The SDK starts both and takes whichever answers first.

Why host.hello exists​

A host that creates an iframe and only then attaches its listener may miss the one-shot map.ready event. host.hello makes readiness pollable and reports the SDK build for install-base measurement.

Maps built before this command answer UNSUPPORTED. The SDK falls back to waiting for map.ready.

Commands sent before map.loaded are queued (bounded at 50 entries, 30 second TTL). ui.setChrome, events.subscribe, and events.unsubscribe skip the queue.

capabilities is a list of command names this build supports — use it for feature detection before sending.