SDK reference

View as MarkdownPlain text for LLMs Open in ClaudeAsk questions about this page Open in ChatGPTAsk questions about this page

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>

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.

Signature

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`	Set to false for quests with no timer, such as a survey.
`options.mediaDriven`	`boolean`	Set to true when real media playback drives the timer.

Returns: A Promise of QuestSession.

Example

const session = await client.startQuest(23);
await session.waitForDuration();
const question = await session.getQuestion();
const result = await session.complete(question.options[0].id);

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>

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.

Signature

getQuestExecution(questId: number): Promise<QuestExecution>

Parameter	Type	Description
`questId` required	`number`	Quest 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>

Parameter	Type	Description
`questId` required	`number`	Quest ID.
`stepKey` required	`string`	The 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>

Parameter	Type	Description
`questId` required	`number`	Quest ID.
`stepKey` required	`string`	The step’s key.
`input`	`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.

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>>

Parameter	Type	Description
`questId` required	`number`	Quest 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.

Signature

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.

Signature

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.

Signature

visitQuest(questId: number): Promise<{ redirectUrl: string }>

Parameter	Type	Description
`questId` required	`number`	Quest ID.

Returns: A Promise of { redirectUrl }.

ingestQuestEvent

Sends an event for an event or custom quest. Sending the same eventId again returns duplicate: true.

Signature

ingestQuestEvent(questId: number, payload: QuestEventPayload): Promise<{ eventId: string; duplicate: boolean }>

Parameter	Type	Description
`questId` required	`number`	Quest ID.
`payload.eventId` required	`string`	Your unique ID for the event.
`payload.eventName` required	`string`	The event the quest is waiting for.
`payload.timestamp` required	`string`	When the event happened.
`payload.signature`	`string`	Signature for server-signed events.
`payload.deliveryToken`	`string`	Token from the quest start.
`payload.source`	`string`	Where the event came from.

Returns: A Promise of { eventId, duplicate }.

getGrowthStatus

Returns the user’s state on a profile, referral, streak or custom quest. Needs a user and a participant token.

Signature

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.

Signature

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.

Signature

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.

attributeReferral

Credits the inviter when a new user arrives with their referral code. Referral quests only.

Signature

attributeReferral(questId: number, referralCode: string, deviceFingerprint?: string): Promise<Record<string, unknown>>

Parameter	Type	Description
`questId` required	`number`	Quest ID.
`referralCode` required	`string`	The inviter’s code.
`deviceFingerprint`	`string`	An optional device fingerprint.

Returns: A Promise of the attribution result.

getQuestStats

Returns engagement counts for the quest on your platform.

Signature

getQuestStats(questId: number): Promise<QuestStats>

Parameter	Type	Description
`questId` required	`number`	Quest ID.

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

Next steps

Quest sessionThe object startQuest returns.Reward methodsBalance, lotteries and claims.Quest evidenceThe proof each format needs.