Skip to main content
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.
When you bind a session token to an 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.