Skip to documentation
AdQuestDocs

Participant sessions

Connect your app’s signed-in user to an AdQuest participant without exposing your private secret.

On this page

Prerequisites

  • A platform that is accepted and active.
  • Your Secret Key (aqs_), stored on your server.
  • Users who are already signed in to your app.

How identity flows

  1. The user signs in to your application using your existing authentication.

  2. Your frontend calls an authenticated endpoint on your own backend.

  3. Your backend reads the user ID from the verified session and calls AdQuest with the Secret Key.

  4. Return the participant token and expiry to that user’s frontend. Initialize the SDK with the same external user ID.

Create a participant token

Node / Next.js backend helper
// Server only. Call this AFTER verifying your application's login session.
Highlighted: export async function createParticipantSession(user: { id: string; name?: string }, locale?: string) {
  const baseUrl = process.env.ADQUEST_API_URL;
  const secret = process.env.ADQUEST_PLATFORM_SECRET;
  if (!baseUrl || !secret) throw new Error("AdQuest is not configured");

  const response = await fetch(baseUrl.replace(/[/]$/, "") + "/platform/participant-sessions", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "X-AdQuest-Platform-Secret": secret,
    },
Highlighted:     body: JSON.stringify({ external_user_id: user.id, display_name: user.name, locale }),
    cache: "no-store",
  });
  const result = await response.json();
  if (!response.ok || !result.status || !result.data?.participant_token) {
    throw new Error("Could not create participant session");
  }
  return {
    externalUserId: user.id,
    participantToken: result.data.participant_token,
    expiresAt: result.data.expires_at,
    expiresIn: result.data.expires_in,
  };
}

Expose the helper as your own authenticated route, such as POST /api/adquest/session. Your route must:

  • Return 401 when your session lookup fails.
  • Protect cookie-based requests against CSRF.
  • Send Cache-Control: no-store.
  • Rate-limit session creation.
  • Never return the Secret Key or log the participant token.

Auto-start quests

A publisher can mark a Reach a target quest as Starts on its own, and a White Label publisher a Custom, Referral or Multi-step quest too. Nothing changes in your code: the participant session you already create starts these quests.

  1. Your backend calls POST /platform/participant-sessions as usual.

  2. AdQuest starts every live auto-start Custom, Referral and Multi-step quest this user has not started yet, after the session is saved. It is never repeated for the same quests, and it never delays or fails the session response.

  3. The quest list returns those quests with status in_progress and auto_start true. The widget shows Continue instead of Start.

  4. When the user taps Continue, the SDK calls start as usual and the same attempt continues. Your server sends evidence for it as for any Custom quest.

FormatAuto-start
CustomStarted on the participant session. No time limit.
ReferralCounts from launch. With Starts on its own it is also started on the participant session and listed as in_progress.
Reach a targetOnly when the publisher chose Starts on its own (enrollment auto): counts from launch for everyone and is listed as in_progress. Otherwise it waits for Start.
StreakAlways counts from launch.
Multi-stepStarted on the participant session when it has no total view cap. The first step the user acts on begins the attempt, and its time limit counts from there.
Video, banner, survey, quiz, visit, profileNever. They wait for Start.

Language and country

Language is set in two places that must match: your backend sends locale when it creates the participant session, and the widget or embed gets the same locale for its own text. Your frontend picks the language and passes it to your backend. The browser SDK never chooses a language, creates sessions or sends the Secret Key.

SettingRule
Supported valuesEnglish (en) and Persian (fa), with region tags such as en-US. Missing, invalid or unsupported values use the platform’s default language, or English when the platform has none. Persian switches the interface to right-to-left.
Widget or embed text and directionThe locale you pass to the widget or embed. If omitted, the platform’s default language, otherwise English. Nothing is read from the browser.
Which quests and lottery text loadThe locale in the participant session request, stored with the session. The response data.locale_resolution shows { requested, effective, source }, where source is host (your locale was used), platform_default (the platform’s default language was used) or legacy_en (English was used). Send the same value you give the widget.
When the user changes languageCreate a new participant session with the new locale, then update the widget or embed.
Reward countryNever taken from the language. Your backend sends country_code when it creates the session. AdQuest never derives it from locale, browser language, Accept-Language, timezone, IP address or host_context.
Browser languageNever read automatically. If you want it, call browserLocales() from @adquest/sdk, pick a supported value, and pass that value as your explicit locale to both the session request and the widget. The helper returns up to 8 browser languages, or an empty list on the server.

Expiry, refresh and logout

  1. Keep the token and expiresAt in memory for the active user. Refresh through your backend before expiry or when AdQuestWidget calls onAuthRequired.

  2. Pass the refreshed value as participantToken. A headless client uses client.setParticipantToken(token); the bridge uses adquest:setParticipantToken.

  3. On logout or user change, remove the widget / WebView and clear its participant state. Mint a new token and remount for the new user. Do not reuse the previous user’s quests or balance.

Profile and host context

Optional host_context in the backend request
{
  "version": 1,
  "displayName": "Ada",
  "locale": "en-US",
  "timezone": "Asia/Tehran",
  "location": { "status": "unavailable" },
  "push": { "status": "denied" },
  "capabilities": {
    "profile": "granted", "location": "unavailable",
    "push": "denied", "custom": "unavailable"
  }
}

Add host_context for profile quests. Send only what the user allowed.

  • Supported fields: display_name, username, email, phone, avatar_url, locale and timezone.
  • location, push and capabilities use granted, denied or unavailable.
  • Keep host_context at or below 8 KB.
  • Save profile changes in your app, then create a new participant session. A frontend-only change does not prove a profile requirement.

Referral code

For referral quests that use your own invite codes, send the participant’s code as referral_code in the session request.

  • 1 to 32 letters or digits. AdQuest stores it upper-case.
  • Each participant holds one code, and a code is unique on your platform: sending it for another participant moves it there.
  • Leave it out, or send it empty, to keep the code already stored.
  • An invalid code fails the whole session request with 422 VALIDATION_ERROR, so validate it before you send it.

Winner contact

FlowWhat you sendWhat AdQuest does
Email on every sessionThe participant session includes email and display name.After the draw, AdQuest emails the stored address.
Email after the winThe session sends only external_user_id. After lottery.winner, your backend posts the winner email to POST /platform/lottery-claims/{claim}/contact.AdQuest emails the address you post.
Claim in the appThe session sends only external_user_id, and you do not post an email.The winner submits the claim form in the widget. AdQuest does not send a win email.

Next steps

Something unclear, missing or wrong here? Tell us