# Quest session

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

Source: https://dashboard.adquest.io/docs/sdk/quest-session · Audience: Developers · Section: SDK reference

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

### `remainingSeconds`

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

```typescript
remainingSeconds(): number | null
```

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

### `questionRemainingSeconds`

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

```typescript
questionRemainingSeconds(): number | null
```

**Returns:** Seconds, or null without a schedule.

### `answeredCount`

How many questions of this attempt the server has taken.

```typescript
answeredCount(): number
```

**Returns:** A count.

## Timing

### `getState`

Returns the current state of the session.

```typescript
getState(): QuestSessionState
```

**Returns:** A QuestSessionState.

### `onProgress`

Subscribes to timer progress. Unsubscribe when the view unmounts.

```typescript
onProgress(callback: (progress: QuestSessionProgress) => void): () => void
```

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| callback | (progress) => void | yes | Called with { elapsed, total, percent, isComplete }. |

**Returns:** A function that removes the listener.

### `syncMediaProgress`

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

```typescript
syncMediaProgress(elapsed: number, total: number): void
```

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| elapsed | number | yes | Seconds played. |
| total | number | yes | Total seconds. |

**Returns:** Nothing.

### `completeDuration`

Marks the timer as finished.

```typescript
completeDuration(): void
```

**Returns:** Nothing.

### `waitForDuration`

Resolves when the required watch time has passed.

```typescript
waitForDuration(): Promise<void>
```

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

## Questions and completion

### `registerClick`

Records a real click on the quest’s media.

```typescript
registerClick(): Promise<void>
```

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

### `getQuestion`

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

```typescript
getQuestion(): Promise<QuestQuestion>
```

**Returns:** A Promise of QuestQuestion.

### `getQuestions`

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.

```typescript
getQuestions(): Promise<QuestQuestion[]>
```

**Returns:** A Promise of QuestQuestion[].

### `answer`

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.

```typescript
answer(questionId: number, value: string | number | { optionId?: number; freeText?: string }, options?: { recheckFailed?: boolean }): Promise<QuestAnswerResult>
```

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| questionId | number | yes | The question being answered. |
| value | string \| number \| { optionId?, freeText? } | yes | The option the participant chose, or their text. |
| options.recheckFailed | boolean | no | 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.

### `complete`

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

```typescript
complete(answer?: string | number | SurveyAnswerInput[]): Promise<QuestCompleteResult>
```

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| answer | string \| number \| SurveyAnswerInput[] | no | 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? }.

> **Read the settlement.** Check status before you show a reward. settlementStatus is pending when the response says completed: false or state: processing. Otherwise it is the server’s settlement_status when it sends one, then success when status is true, and failed otherwise. An accepted answer is polled a few times before complete returns, so a result can still come back pending, and a pending result can still be rejected after review.

### `checkAttempt`

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.

```typescript
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.

### `awaitSettlement`

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

```typescript
awaitSettlement(): Promise<QuestCompleteResult>
```

**Returns:** A Promise of QuestCompleteResult.

### `submitReview`

Submits evidence for a quest that is checked by review.

```typescript
submitReview(evidence: string): Promise<QuestCompleteResult>
```

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| evidence | string | yes | 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.

- [Quest methods](https://dashboard.adquest.io/docs/sdk/quests): The client versions of these methods.
