Browser navigation protocol
This optional parent/iframe messaging protocol does not affect launch_url. Every message contains channel="api-client.navigation", version=1 and instanceId.
- The loader sends hello to its direct parent with a random instanceId and no credentials.
- The parent may reply with capabilities and returnToPlatform=true, echoing instanceId.
- A game return request sends request-return with requestId.
- The parent acknowledges with return-accepted and the same requestId. Without acknowledgement, the loader revokes the return capability.
Validate event.source against the current iframe.contentWindow, event.origin against the launch URL origin, and the current instanceId. Clean up old instances on remount. Accepting return does not mean the player has exited or the wallet is closed. Calling kick depends on an explicit platform exit action.
request-return may include confirmed=true when the player already confirmed return in a game error dialog. The parent can close the window and refresh the wallet without another confirmation. Ordinary requests follow the platform's confirmation flow.
capabilities may also include loaderReady=true. The loader sends ready when it can take over the loading indicator. After origin validation, the parent removes its outer indicator. ready does not mean game assets, login or round restoration are complete; iframe load is not proof of business readiness. On timeout, retain a return or relaunch action.
The channel is a public contract and remains unchanged after the source directory moved to provider/client.
Examples
These are postMessage objects, not HTTP APIs. Every message includes channel, version, type and instanceId. Return requests and acknowledgements also include requestId, echoed unchanged.
{"channel":"api-client.navigation","version":1,"type":"hello","instanceId":"INSTANCE_ID"}
{
"channel":"api-client.navigation",
"version":1,
"type":"capabilities",
"instanceId":"INSTANCE_ID",
"returnToPlatform":true,
"loaderReady":true
}
| type | Direction | Additional fields / action |
|---|---|---|
| hello | iframe → parent | Save instanceId and declare supported capabilities |
| capabilities | parent → iframe | Optional booleans returnToPlatform and loaderReady |
| ready | iframe → parent | Remove outer loading indicator; not a login completion event |
| request-return | iframe → parent | String requestId; optional boolean confirmed |
| return-accepted | parent → iframe | Echo requestId; acknowledges only UI return handling |
Use the verified game origin as targetOrigin, never *. This protocol does not carry secrets, API tokens or wallet balances.