Quickstart Guide

Prerequisites

• An accepted AdQuest platform with public_id, public API key, and platform secret
• A backend that can call AdQuest with the platform secret
• A web page or WebView that can host an iframe

1. Mint a participant token

Never put the platform secret in client code.

POST https://api.adquest.io/api/v1/platform/participant-sessions
X-AdQuest-Platform-Secret: YOUR_PLATFORM_SECRET
Content-Type: application/json

{
  "external_user_id": "host-user-123",
  "display_name": "Ada"
}

Response includes participant_token and expiry. Return the token to your client.

2. Open the embed

https://sdk.adquest.io/{publicId}?host=1

Use host=1 when the host chrome (back button / title) is outside the iframe.

3. Initialize after ready

window.addEventListener("message", (event) => {
  if (event.origin !== "https://sdk.adquest.io") return;
  if (event.data?.type === "adquest:ready") {
    iframe.contentWindow.postMessage(
      {
        version: 1,
        type: "adquest:init",
        payload: {
          apiKey: "AQK-...",
          externalUserId: "host-user-123",
          participantToken: participantToken,
          view: "quests",
        },
      },
      "https://sdk.adquest.io"
    );
  }
});

4. Handle auth refresh

When you receive adquest:authRequired (or React onAuthRequired), mint a new participant token and send adquest:setParticipantToken.

Local development

Point the embed and API to your local stack (for example SDK http://127.0.0.1:4081 and API http://127.0.0.1:8001/api/v1) and keep the same init flow.