XMPlay SDK v2
XMPlay Integration Docs
Quick Start
Listen for the xmp_inject message in your game HTML to receive host-injected params:
window.addEventListener('message', (e) => {
if (e.data?.type === 'xmp_inject') {
const { params, gameId } = e.data;
// Apply params to your game
initGame(params);
}
});
// Signal ready to the host
window.parent.postMessage({
type: 'xmp_ack',
gameId: window.__XMP_GAME_ID ?? 'unknown',
payload: { lifecycle: 'ready' },
}, '*');Message Types
| Type | Direction | Description |
|---|---|---|
| xmp_inject | Host → Game | Inject initial params (fired after lifecycle:ready) |
| xmp_control | Host → Game | Send control commands (restart/mute/pause/etc.) |
| xmp_ack | Game → Host | Game acknowledgement (lifecycle/score/log/etc.) |
Sandbox Attributes
All XMP games run in a controlled iframe with the following sandbox attributes:
<!-- Standard XMP formats -->
sandbox="allow-scripts allow-same-origin allow-pointer-lock
allow-storage-access-by-user-activation"
allow="autoplay; fullscreen; picture-in-picture"
<!-- xmp-cc format (adds form/popup/download capabilities) -->
sandbox="allow-scripts allow-same-origin allow-pointer-lock
allow-storage-access-by-user-activation
allow-forms allow-popups allow-downloads"Lifecycle
Recommended game lifecycle event sequence:
// 1. DOM ready → signal ready
window.parent.postMessage({ type: 'xmp_ack', payload: { lifecycle: 'ready' } }, '*');
// 2. Host fires xmp_inject with params
// → Your game initialises with injected params
// 3. Game loop starts → optional: report score
window.parent.postMessage({
type: 'xmp_ack',
payload: { lifecycle: 'score', value: 1234 }
}, '*');
// 4. Game ends → signal complete
window.parent.postMessage({
type: 'xmp_ack',
payload: { lifecycle: 'complete', score: 9999 }
}, '*');