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
The user signs in to your application using your existing authentication.
Your frontend calls an authenticated endpoint on your own backend.
Your backend reads the user ID from the verified session and calls AdQuest with the Secret Key.
Return the participant token and expiry to that user’s frontend. Initialize the SDK with the same external user ID.
Create a participant token
// 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.
Your backend calls POST /platform/participant-sessions as usual.
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.
The quest list returns those quests with status in_progress and auto_start true. The widget shows Continue instead of Start.
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.
| Format | Auto-start |
|---|---|
| Custom | Started on the participant session. No time limit. |
| Referral | Counts from launch. With Starts on its own it is also started on the participant session and listed as in_progress. |
| Reach a target | Only 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. |
| Streak | Always counts from launch. |
| Multi-step | Started 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, profile | Never. 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.
| Setting | Rule |
|---|---|
| Supported values | English (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 direction | The 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 load | The 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 language | Create a new participant session with the new locale, then update the widget or embed. |
| Reward country | Never 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 language | Never 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
Keep the token and expiresAt in memory for the active user. Refresh through your backend before expiry or when AdQuestWidget calls onAuthRequired.
Pass the refreshed value as participantToken. A headless client uses client.setParticipantToken(token); the bridge uses adquest:setParticipantToken.
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
{
"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
| Flow | What you send | What AdQuest does |
|---|---|---|
| Email on every session | The participant session includes email and display name. | After the draw, AdQuest emails the stored address. |
| Email after the win | The 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 app | The 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. |