Ad QuestLogin/Signup
← Back to Blog

Embedding the AdQuest SDK in a host app

A practical guide to participant sessions, the hosted embed URL, and the postMessage bridge for web and WebView hosts.

By AdQuest Engineering

AdQuest ships as a lottery-first SDK with quests inside the same experience. Hosts never put the platform secret in the browser. Instead, your backend mints a short-lived participant token and the client initializes with the public platform key.

The two integration paths

Hosted embed

Open https://sdk.adquest.io/{publicId} in an iframe or WebView. Branding loads from public config. After adquest:ready, send adquest:init with apiKey, externalUserId, and participantToken.

React widget

Install @adquest/sdk, import @adquest/sdk/styles.css, and render AdQuestWidget with the same credentials. Use QuestWidget when you only need quests.

Participant sessions

On your server:

POST /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"
}

Return participant_token to the client. Refresh it when the SDK emits onAuthRequired.

Bridge events that matter

  • onReady — embed is live
  • onComplete — quest finished; tokens may have been awarded
  • onEntry — lottery entry purchased
  • onClaim — reward claim submitted
  • onNavigate — { view, canGoBack } for chrome that mirrors SDK navigation
  • onClose — user asked to dismiss

Security checklist

  • Keep ADQUEST_PLATFORM_SECRET on the server only
  • Scope tokens per external user id
  • Prefer HTTPS everywhere
  • Treat client API keys as public identifiers, not secrets

Full reference lives in Developer Docs under Embed and Authentication.