Quest session
The object startQuest returns. It tracks the timer, the question and the completion of one quest.
On this page
Members
| Member | Type | Meaning |
|---|---|---|
| questId | number | The quest this session belongs to. |
| displayDuration | number | Seconds the quest must be shown or watched. |
| deliveryToken | string | undefined | Token from the start, sent back when you complete. |
| reservationId | string | undefined | The server’s reservation for this attempt. The session names it on every request. |
| attemptsLeft | number | undefined | Attempts allowed after this one. 0 means a failed or expired attempt cannot be started again. |
| expiresAt | string | undefined | The attempt’s hard deadline, in server time (ISO). Starting again returns the same one. |
| timing | QuestTiming | undefined | The server’s schedule: displaySeconds, answerSeconds, gapSeconds, questionCount, and optional watchEnd, questionDueAt and answeredCount. |
| supportsAnswers | boolean | True 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.
remainingSeconds(): number | nullReturns: 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.
questionRemainingSeconds(): number | nullReturns: Seconds, or null without a schedule.
How many questions of this attempt the server has taken.
answeredCount(): numberReturns: A count.
Timing
Returns the current state of the session.
getState(): QuestSessionStateReturns: A QuestSessionState.
Subscribes to timer progress. Unsubscribe when the view unmounts.
onProgress(callback: (progress: QuestSessionProgress) => void): () => void| Parameter | Type | Description |
|---|---|---|
callback required | (progress) => void | Called with { elapsed, total, percent, isComplete }. |
Returns: A function that removes the listener.
Feeds real video playback into the session. Use it with mediaDriven: true.
syncMediaProgress(elapsed: number, total: number): void| Parameter | Type | Description |
|---|---|---|
elapsed required | number | Seconds played. |
total required | number | Total seconds. |
Returns: Nothing.
Marks the timer as finished.
completeDuration(): voidReturns: Nothing.
Resolves when the required watch time has passed.
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.
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.
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.
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.
answer(questionId: number, value: string | number | { optionId?: number; freeText?: string }, options?: { recheckFailed?: boolean }): Promise<QuestAnswerResult>| Parameter | Type | Description |
|---|---|---|
questionId required | number | The question being answered. |
value required | string | number | { optionId?, freeText? } | The option the participant chose, or their text. |
options.recheckFailed | boolean | The 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.
complete(answer?: string | number | SurveyAnswerInput[]): Promise<QuestCompleteResult>| Parameter | Type | Description |
|---|---|---|
answer | string | 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.
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.
awaitSettlement(): Promise<QuestCompleteResult>Returns: A Promise of QuestCompleteResult.
Submits evidence for a quest that is checked by review.
submitReview(evidence: string): Promise<QuestCompleteResult>| Parameter | Type | Description |
|---|---|---|
evidence required | string | The 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.