Skip to documentation
AdQuestDocs

Quest session

The object startQuest returns. It tracks the timer, the question and the completion of one quest.

On this page

Members

MemberTypeMeaning
questIdnumberThe quest this session belongs to.
displayDurationnumberSeconds the quest must be shown or watched.
deliveryTokenstring | undefinedToken from the start, sent back when you complete.
reservationIdstring | undefinedThe server’s reservation for this attempt. The session names it on every request.
attemptsLeftnumber | undefinedAttempts allowed after this one. 0 means a failed or expired attempt cannot be started again.
expiresAtstring | undefinedThe attempt’s hard deadline, in server time (ISO). Starting again returns the same one.
timingQuestTiming | undefinedThe server’s schedule: displaySeconds, answerSeconds, gapSeconds, questionCount, and optional watchEnd, questionDueAt and answeredCount.
supportsAnswersbooleanTrue when questions are answered one at a time with answer, each against its own deadline.

Seconds left until the hard deadline, corrected for clock skew.

Signature
remainingSeconds(): number | null

Returns: Seconds, or null when the attempt has no deadline.

Seconds left to answer the current question, or until the hard deadline if that comes first.

Signature
questionRemainingSeconds(): number | null

Returns: Seconds, or null without a schedule.

How many questions of this attempt the server has taken.

Signature
answeredCount(): number

Returns: A count.

Timing

Returns the current state of the session.

Signature
getState(): QuestSessionState

Returns: A QuestSessionState.

Subscribes to timer progress. Unsubscribe when the view unmounts.

Signature
onProgress(callback: (progress: QuestSessionProgress) => void): () => void
ParameterTypeDescription
callback required(progress) => voidCalled with { elapsed, total, percent, isComplete }.

Returns: A function that removes the listener.

Feeds real video playback into the session. Use it with mediaDriven: true.

Signature
syncMediaProgress(elapsed: number, total: number): void
ParameterTypeDescription
elapsed requirednumberSeconds played.
total requirednumberTotal seconds.

Returns: Nothing.

Marks the timer as finished.

Signature
completeDuration(): void

Returns: Nothing.

Resolves when the required watch time has passed.

Signature
waitForDuration(): Promise<void>

Returns: A Promise that resolves when the timer is done.

Questions and completion

Records a real click on the quest’s media.

Signature
registerClick(): Promise<void>

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

Loads the first question of a video, banner, quiz or survey quest.

Signature
getQuestion(): Promise<QuestQuestion>

Returns: A Promise of QuestQuestion.

Loads every question of the attempt, in the order the server asks them. A video, banner or quiz quest can have several; after a refresh the order resumes where the server left off.

Signature
getQuestions(): Promise<QuestQuestion[]>

Returns: A Promise of QuestQuestion[].

Sends one answer when supportsAnswers is true. A first miss on a graded question returns correct: false and the question is asked again at the end. Past the deadline nothing is sent and the result says the time is over.

Signature
answer(questionId: number, value: string | number | { optionId?: number; freeText?: string }, options?: { recheckFailed?: boolean }): Promise<QuestAnswerResult>
ParameterTypeDescription
questionId requirednumberThe question being answered.
value requiredstring | number | { optionId?, freeText? }The option the participant chose, or their text.
options.recheckFailedbooleanThe survey re-check before this last answer did not match. The server ends the attempt instead of taking the answer.

Returns: A Promise of { done, answeredCount, questionDueAt?, correct?, result? }. When done is true, result holds the QuestCompleteResult.

Submits the participant’s answer. Never choose the answer for them.

Signature
complete(answer?: string | number | SurveyAnswerInput[]): Promise<QuestCompleteResult>
ParameterTypeDescription
answerstring | number | SurveyAnswerInput[]The chosen option ID, or the answers of a multi-question survey.

Returns: A Promise of { status, questId, completedAt?, reason?, rejectionCode?, settlementStatus, tokensAwarded?, tokenReward?, unitAwarded? }.

Asks the server whether the attempt was accepted, settled or ended, and polls up to 4 more times while it is still being processed. Use it after a lost response or an expired timer instead of submitting again.

Signature
checkAttempt(): Promise<QuestCompleteResult | null>

Returns: A Promise of QuestCompleteResult, or null while the attempt is open and nothing was submitted, or when the server cannot be asked.

Polls the server 12 times over about 40 seconds. It never submits again. The result can still be pending: check settlementStatus.

Signature
awaitSettlement(): Promise<QuestCompleteResult>

Returns: A Promise of QuestCompleteResult.

Submits evidence for a quest that is checked by review.

Signature
submitReview(evidence: string): Promise<QuestCompleteResult>
ParameterTypeDescription
evidence requiredstringThe evidence the quest asks for.

Returns: A Promise of QuestCompleteResult.

Growth quests

The session also exposes getGrowthStatus, getStreakStatus and getCustomStatus for the quest it was started for. They take the same arguments as the client methods, without the quest ID.

Something unclear, missing or wrong here? Tell us