Skip to documentation
AdQuestDocs

Quest methods

Client methods for listing quests, starting them and sending evidence.

On this page

getQuests

Lists the quests this platform can show. If a user is set, each quest’s completed flag is filled in.

Signature
getQuests(): Promise<Quest[]>

Returns: A Promise of Quest[].

Example
const quests = await client.getQuests();

getQuest

Loads one quest.

Signature
getQuest(questId: number): Promise<Quest>
ParameterTypeDescription
questId requirednumberQuest ID.

Returns: A Promise of Quest.

startQuest

Starts a quest for the current user and returns a QuestSession that tracks the rest of the flow. Needs a user and a participant token. Starting again too soon throws RESTART_TOO_SOON; details.retry_after says how many seconds to wait.

Signature
startQuest(questId: number, options?: StartQuestOptions): Promise<QuestSession>
ParameterTypeDescription
questId requirednumberQuest ID.
options.watchDurationnumberSeconds the participant must watch, for timed quests.
options.requiresTimerbooleanDefaults to false. Set it to true for a video or banner quest, so getQuestion, getQuestions and complete throw TIMER_NOT_STARTED until the watch time has passed. Wait with waitForDuration() first.
options.mediaDrivenbooleanSet to true when real media playback drives the timer.

Returns: A Promise of QuestSession.

Example
const session = await client.startQuest(23, { requiresTimer: true });
await session.waitForDuration();
const questions = await session.getQuestions();
// showQuestion is your own UI: it resolves with the option the participant chose.
let result;
if (session.supportsAnswers) {
  for (const question of questions) {
    const answered = await session.answer(question.id, await showQuestion(question));
    if (answered.done) { result = answered.result; break; }
    // A first miss on a graded question (answered.correct === false) is asked once more after the others.
  }
} else {
  result = await session.complete(await showQuestion(questions[0]));
}

awaitCompletion

Returns where the participant’s attempt at this quest stands, and polls while it is being settled. Needs a user and a participant token.

Signature
awaitCompletion(questId: number, options?: { signal?: AbortSignal; untilSettled?: boolean }): Promise<QuestCompleteResult>
ParameterTypeDescription
questId requirednumberQuest ID.
options.signalAbortSignalAbort the polling, for example when the screen closes.
options.untilSettledbooleanKeep polling until the attempt is settled.

Returns: A Promise of QuestCompleteResult.

getQuestExecution

Reads the participant’s multi-step execution: the definition version it runs on, every step with its status, and the settlement status of the parent quest. Needs a participant token.

Signature
getQuestExecution(questId: number): Promise<QuestExecution>
ParameterTypeDescription
questId requirednumberQuest ID.

Returns: A Promise of QuestExecution.

Example
const execution = await client.getQuestExecution(23);

getQuestStep

Reads one step of a multi-step execution, including its manual-review status. Needs a participant token.

Signature
getQuestStep(questId: number, stepKey: string): Promise<QuestStepState>
ParameterTypeDescription
questId requirednumberQuest ID.
stepKey requiredstringThe step’s key.

Returns: A Promise of QuestStepState.

Example
const step = await client.getQuestStep(23, "proof");

submitQuestStepEvidence

Asks the server to verify one step. The server decides; a completed flag is never sent. Use action start or click for timed and visit steps, evidence for manual review and answers for survey steps.

Signature
submitQuestStepEvidence(questId: number, stepKey: string, input: StepEvidenceInput, attempt?: StepAttempt): Promise<QuestStepState>
ParameterTypeDescription
questId requirednumberQuest ID.
stepKey requiredstringThe step’s key.
input requiredStepEvidenceInputaction, evidence, evidenceType or answers.
attemptStepAttemptThe reservation id and delivery token of the current attempt.

Returns: A Promise of QuestStepState; read status in_review for a step awaiting review.

Example
const step = await client.submitQuestStepEvidence(23, "proof", { evidence: "receipt-123" });

getQuestReview

Reads where the participant’s manual review stands. Needs a participant token.

Signature
getQuestReview(questId: number): Promise<Record<string, unknown>>
ParameterTypeDescription
questId requirednumberQuest ID.

Returns: A Promise of the review record.

Example
const review = await client.getQuestReview(23);

trackView

Records that the user saw the quest. Needs a user and a participant token.

Signature
trackView(questId: number): Promise<void>
ParameterTypeDescription
questId requirednumberQuest ID.

Returns: A Promise that resolves when the view is recorded.

trackClick

Records a real click on the quest’s media. Needs a user and a participant token.

Signature
trackClick(questId: number): Promise<void>
ParameterTypeDescription
questId requirednumberQuest ID.

Returns: A Promise that resolves when the click is recorded.

visitQuest

Attributes a visit for a visit quest and returns the destination. Needs a user and a participant token.

Signature
visitQuest(questId: number): Promise<{ redirectUrl: string }>
ParameterTypeDescription
questId requirednumberQuest ID.

Returns: A Promise of { redirectUrl }.

getGrowthStatus

Returns the user’s state on an event, profile, referral, streak or custom quest: progress toward an event goal, the referral code, streak days or the custom review. Needs a user and a participant token.

Signature
getGrowthStatus(questId: number): Promise<GrowthStatus>
ParameterTypeDescription
questId requirednumberQuest ID.

Returns: A Promise of GrowthStatus.

Returns the streak part of the growth status.

Signature
getStreakStatus(questId: number): Promise<StreakStatus | null>
ParameterTypeDescription
questId requirednumberQuest ID.

Returns: A Promise of StreakStatus, or null when the quest has none.

Returns the custom-quest part of the growth status.

Signature
getCustomStatus(questId: number): Promise<CustomStatus | null>
ParameterTypeDescription
questId requirednumberQuest ID.

Returns: A Promise of CustomStatus, or null when the quest has none.

getQuestStats

Returns engagement counts for the quest on your platform.

Signature
getQuestStats(questId: number): Promise<QuestStats>
ParameterTypeDescription
questId requirednumberQuest ID.

Returns: A Promise of { id, name, seenCount, clickedCount, answeredCount, engagementRate }.

Next steps

Something unclear, missing or wrong here? Tell us