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.
getQuests(): Promise<Quest[]>Returns: A Promise of Quest[].
const quests = await client.getQuests();getQuest
Loads one quest.
getQuest(questId: number): Promise<Quest>| Parameter | Type | Description |
|---|---|---|
questId required | number | Quest 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.
startQuest(questId: number, options?: StartQuestOptions): Promise<QuestSession>| Parameter | Type | Description |
|---|---|---|
questId required | number | Quest ID. |
options.watchDuration | number | Seconds the participant must watch, for timed quests. |
options.requiresTimer | boolean | Defaults 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.mediaDriven | boolean | Set to true when real media playback drives the timer. |
Returns: A Promise of QuestSession.
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.
awaitCompletion(questId: number, options?: { signal?: AbortSignal; untilSettled?: boolean }): Promise<QuestCompleteResult>| Parameter | Type | Description |
|---|---|---|
questId required | number | Quest ID. |
options.signal | AbortSignal | Abort the polling, for example when the screen closes. |
options.untilSettled | boolean | Keep 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.
getQuestExecution(questId: number): Promise<QuestExecution>| Parameter | Type | Description |
|---|---|---|
questId required | number | Quest ID. |
Returns: A Promise of QuestExecution.
const execution = await client.getQuestExecution(23);getQuestStep
Reads one step of a multi-step execution, including its manual-review status. Needs a participant token.
getQuestStep(questId: number, stepKey: string): Promise<QuestStepState>| Parameter | Type | Description |
|---|---|---|
questId required | number | Quest ID. |
stepKey required | string | The step’s key. |
Returns: A Promise of QuestStepState.
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.
submitQuestStepEvidence(questId: number, stepKey: string, input: StepEvidenceInput, attempt?: StepAttempt): Promise<QuestStepState>| Parameter | Type | Description |
|---|---|---|
questId required | number | Quest ID. |
stepKey required | string | The step’s key. |
input required | StepEvidenceInput | action, evidence, evidenceType or answers. |
attempt | StepAttempt | The reservation id and delivery token of the current attempt. |
Returns: A Promise of QuestStepState; read status in_review for a step awaiting review.
const step = await client.submitQuestStepEvidence(23, "proof", { evidence: "receipt-123" });getQuestReview
Reads where the participant’s manual review stands. Needs a participant token.
getQuestReview(questId: number): Promise<Record<string, unknown>>| Parameter | Type | Description |
|---|---|---|
questId required | number | Quest ID. |
Returns: A Promise of the review record.
const review = await client.getQuestReview(23);trackView
Records that the user saw the quest. Needs a user and a participant token.
trackView(questId: number): Promise<void>| Parameter | Type | Description |
|---|---|---|
questId required | number | Quest 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.
trackClick(questId: number): Promise<void>| Parameter | Type | Description |
|---|---|---|
questId required | number | Quest 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.
visitQuest(questId: number): Promise<{ redirectUrl: string }>| Parameter | Type | Description |
|---|---|---|
questId required | number | Quest 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.
getGrowthStatus(questId: number): Promise<GrowthStatus>| Parameter | Type | Description |
|---|---|---|
questId required | number | Quest ID. |
Returns: A Promise of GrowthStatus.
Returns the streak part of the growth status.
getStreakStatus(questId: number): Promise<StreakStatus | null>| Parameter | Type | Description |
|---|---|---|
questId required | number | Quest ID. |
Returns: A Promise of StreakStatus, or null when the quest has none.
Returns the custom-quest part of the growth status.
getCustomStatus(questId: number): Promise<CustomStatus | null>| Parameter | Type | Description |
|---|---|---|
questId required | number | Quest ID. |
Returns: A Promise of CustomStatus, or null when the quest has none.
getQuestStats
Returns engagement counts for the quest on your platform.
getQuestStats(questId: number): Promise<QuestStats>| Parameter | Type | Description |
|---|---|---|
questId required | number | Quest ID. |
Returns: A Promise of { id, name, seenCount, clickedCount, answeredCount, engagementRate }.