Skip to documentation
AdQuestDocs

Headless JavaScript

Build your own interface with the typed client and use the public API for format-specific completion evidence.

On this page

Prerequisites

  • The SDK installed: npm install @adquest/sdk.
  • Your public API key, API URL and a participant token for the user.

Initialize the client

Client setup
import { createAdQuestClient } from "@adquest/sdk";

const client = createAdQuestClient({
  apiKey: "YOUR_PUBLIC_API_KEY",
  baseUrl: "https://api.adquest.io/api/v1",
  externalUserId: "host-user-123",
  participantToken: "TOKEN_FROM_YOUR_BACKEND",
});
const quests = await client.getQuests();
// Render quests and let the participant choose one.
// On token refresh: client.setParticipantToken(newToken);

Question-based quest sessions

  1. Start the selected quest. Use requiresTimer: false for a survey or a quiz. For a video, pass watchDuration and feed real playback into syncMediaProgress(elapsed, total).

  2. For timed media, wait for session.waitForDuration(). Render the questions returned by getQuestions().

  3. When session.supportsAnswers is true, send each answer as the participant gives it with session.answer(questionId, value) and show questionRemainingSeconds() as the time left. A quiz answer that returns correct: false is a first miss: that question comes back at the end. The answer that returns done: true carries the result.

  4. When supportsAnswers is false (a server without reservations), submit the chosen option with session.complete(optionId), or a SurveyAnswerInput[] for a multi-question survey.

  5. If a response is lost or result.settlementStatus is pending, call session.awaitSettlement(). It asks the server where the attempt stands for about 40 seconds and never submits twice. It can still return pending: show rewards only when settlementStatus is success, and otherwise tell the participant the reward is on its way. Unsubscribe from progress listeners when the view unmounts.

Send format-specific API requests

Visit, profile and custom quests use the public API directly. Event, referral and streak quests are proven by the activities your server reports. The shared request helper and each format’s calls are in Quest evidence.

Client methods

Every client method has a signature, parameters and an example in the SDK reference.

Next steps

Something unclear, missing or wrong here? Tell us