API reference
Bridge messages
Messages exchanged between your page or native app and the hosted embed.
On this page
Bridge message reference
Every envelope has version 1, a type, and an optional payload. ready includes bridgeVersion and capabilities. navigation includes view and canGoBack. Confirm payment fulfillment on your backend. A payment message is only UI state.
| Direction | Messages |
|---|---|
| Host → embed | adquest:init (hostContext.locale sets the language), adquest:setParticipantToken, adquest:setUser, adquest:setHostContext (payload { locale } changes the language), adquest:setNavigation, adquest:navigate, adquest:goBack, adquest:paymentResult |
| Embed → host | adquest:ready, adquest:navigation, adquest:questComplete, adquest:lotteryEnter, adquest:claimSubmit, adquest:authRequired, adquest:error, adquest:close, adquest:exit, adquest:openUrl, adquest:haptic, adquest:paymentResult |
Payloads
Every message is an envelope: { version: 1, type, payload }. Payloads that are not listed are empty.
| Message | Direction | Payload |
|---|---|---|
| adquest:ready | Embed → host | { bridgeVersion: 1, capabilities: string[] } |
| adquest:init | Host → embed | { apiKey, externalUserId, participantToken } plus optional expiresIn, expiresAt, view, hostContext and navigation ("adquest" default, or "host" when your app provides the header) |
| adquest:setParticipantToken | Host → embed | { participantToken } |
| adquest:setUser | Host → embed | { externalUserId } |
| adquest:setHostContext | Host → embed | The host context object, such as { locale } |
| adquest:setNavigation | Host → embed | { navigation: "adquest" | "host" }. With "host" the embed hides its header and shows Back to platform on the home page |
| adquest:exit | Embed → host | No payload. The user chose Back to platform on the home page |
| adquest:navigate | Host → embed | { view } |
| adquest:navigation | Embed → host | { view, canGoBack } and optional immersive |
| adquest:error | Embed → host | { code, message } |
| adquest:openUrl | Embed → host | { url, target }. target "self" is a link to one of your own pages: navigate in place, never a new tab. target "blank" is an outside destination. On the web without a native bridge the SDK moves the top page itself for "self"; a React host can listen for the cancelable adquest:openUrl event on window (detail.url) and call preventDefault() to route it without a reload. |
| adquest:haptic | Embed → host | { style: "light" | "success" }. A celebration moment (step verified, quest done, streak day). Optional: play a native haptic; iOS WebViews cannot vibrate from the page. |
| adquest:contentReady | Embed → host | { balance?: { x, y } }. Sent once, when the first screen is on the page (or an error message is). Hide your own loading view here; the start splash leaves on it. balance is the centre of the balance chip in the embed’s viewport, when one shows. |
| adquest:paymentResult | Both | { status: success, failed, pending or unknown } plus optional amount and reference |