Embedding is where a world becomes programmable inside your product:
@alakazamworld/embed mounts a world in a sandboxed iframe and bridges it to your
page over an origin-validated postMessage channel, so you can react to its
events and wire it into your own logic. It’s zero-dependency and works with any
framework.
Install
Or via a script tag, which auto-mounts any [data-alakazam-slug] element:
Mount a world
What the live path supports today
With a live-mode session token, /embed/<slug> nests the real streaming
player. Current callback support on that path: onReady (fires when the player
document loads), onError (invalid/expired token). Gameplay events
(onChoice, onStateEntered, onEnding, onSessionEnded), live theming, and
in-flight token refresh require the player event bridge, which is still in
flight, don’t build logic on them yet. Test-mode tokens render a
shape-faithful sandbox handshake page (all synthetic events fire; no stream).
Options beyond the basics: baseUrl (or data-alakazam-base on the script-tag
path) points the SDK at a different API host: you almost never need it; it
exists for staging and local development.
Events
The SDK delivers world events to your callbacks, all over an origin-validated
channel:
Refresh the token
Session tokens are short-lived. Provide onTokenExpiring to hand the SDK a
fresh token from your backend, a re-authorization checkpoint that keeps long
sessions alive without interrupting play:
Theming
Restyle the player’s chrome with a small set of tokens (no raw stylesheet
overrides), then update them live with setTheme:
Cross-origin security
Register the origins you’ll embed on in your app’s settings, and pass the same
origin when minting the session token.
origin, Alakazam:
- sets
Content-Security-Policy: frame-ancestors <origin> on the embed page, so
only your site can frame it, and
- stamps the token’s
aud to that origin, locking which sites can frame the
embed page (the session itself is bearer-authorized by the token, guard the
token like a credential).
The SDK validates the postMessage origin on both ends and never relies on
third-party cookies. 
