# Quest (beta)

## Introduction

If you are implementing a Quest, you can take advantage of the quiz API:s. These offer a set of utilities to create users, fetch and answer challenges and see the top results. You can also hand out prizes (see [Prize (beta)](/moments-sdk/documentation/api-reference/prize.md)). 

To enable the quiz in your WebApp you have to add the **`quest`** plugin to the list of plugins in your **`manifest.json`**.

{% hint style="warning" %}
The Quest will soon replace the Quiz.
{% endhint %}

```javascript
...
"plugins": [ ..., "prizes", "quest" ] 
...
```

The Quest is an object similar to the Quiz, but much more general, in order to account for many different Moment use cases. Among them, the Quest includes quizzes. The "question" entity that you find in the Quiz, it's referred to as "challenge" in the Quest.

## API Docs

### `setContext(questId:string): Promise<Quest>`

This is the first function you should call in order to initialize the quest service. All the following calls will not require the questId.&#x20;

**Params**

* **`questId`**: the id of the quest to be fetched; You will find the questId in the SDK config params.

{% tabs %}
{% tab title="Code" %}

```javascript
const { questId } = await SDK.connection.getMomentClass();

SDK.quest.setContext(questId) 
```

{% endtab %}
{% endtabs %}

### `getQuest(): Promise<Quest>`

{% tabs %}
{% tab title="Code" %}

```javascript
SDK
  .quest
  .getQuest()
  .then(quest => console.log(quest))
  .catch(err => console.error(err)); 
  
/* prints

{
  "id": "abc123",
  "title": "Test Quest",
  "event": "abc123",
  "seriesDuration": 180000,
  "challengeDuration": 20000,
  "challengeCount": 5,
  "prizesPerSeries": 1,
  "challengesPerRound": 3,
  "maxRoundsPerSeries": 200,
  "seriesPlayed": 388
}

*/
```

{% endtab %}
{% endtabs %}

### getChallenge`(id): Promise<ChallengeItem>`

**Params**

* **`id`**: the challenge id;

{% tabs %}
{% tab title="Code" %}

```javascript
SDK
  .quest
  .getChallenge(1)
  .then(challenge => console.log(challenge))
  .catch(err => console.error(err)); 

```

{% endtab %}
{% endtabs %}

### `respondToChallenge(questionHash, answer): Promise<AnswerScore>`

**Params**

* **`questionHash: string`**: the id of the content to be fetched;
* **`answer: number`**: if the content should be compressed or full size.

{% tabs %}
{% tab title="Code" %}

```javascript
let question;
let answer = 2

// fetch the question...
SDK
  .quiz
  .getQuestion(1)
  .then(q => question = q)
  .catch(err => console.error(err)); 
  
  
  
// ... after a few seconds the user selects the answer
  
SDK
  .quiz
  .answerQuestion(question.hash, answer)
  .then(answer => console.log(answer))
  .catch(err => console.error(err)); 
  
/* prints: 
{
  "correctAnswers": [2],
  "questionPoints": 18707,
  "totalPoints": 18707
}
*/
```

{% endtab %}
{% endtabs %}

### `getTopScores(offset?, limit?): Promise<TopScores>`

**Params**

* **`offset`**: the starting position;
* **`limit`**: the number of positions to be fetched.

{% tabs %}
{% tab title="Code" %}

```javascript
SDK
  .quiz
  // fetch the first 50 users
  .getTopScores(0, 50)
  .then(scores => console.log(scores))
  .catch(err => console.error(err)); 
  
/* prints: 
  
{
  "leaderboard": [{
    "userId": "user@stagecast.com",
    "name": "User#9265",
    "bestScore": 52187,
    "position": 1
  },{
    "userId": "anotheruser@stagecast.com",
    "name": "User#1356",
    "bestScore": 50187,
    "position": 2
  }, ..., {
    "userId": "50th@stagecast.com",
    "name": "Baduser#1306",
    "bestScore": 10187,
    "position": 50
  },]
}
  
*/
```

{% endtab %}
{% endtabs %}

### `getUserScores(): Promise<LeaderboardEntry>`

{% tabs %}
{% tab title="Code" %}

```javascript
SDK
  .quiz
  .getUserScores()
  .then(myOwn => console.log(myOwn))
  .catch(err => console.error(err)); 
  
/* prints:

{
  "userId": "user@stagecast.com",
  "name": "User#9265",
  "bestScore": 52187,
  "position": 1
}

*/
```

{% endtab %}
{% endtabs %}

### getUserProfile`(): Promise<Profile>`

It fetches the user profile information

{% tabs %}
{% tab title="Code" %}

```javascript
SDK
  .quest
  .getUserProfile()
  .then(profile => console.log(profile))
  .catch(err => console.error(err)); 
  
/* prints

{
  "userId": "user@stagecast.com",
  "name": "User#9265",
  "points": 52187,
  "bestScore": 52187,
  "momentId": "abc123",
  "prizes": null,
  "questionsAnswered": 0,
  "roundsPlayed": 0,
  "totalRoundsPlayed": 7,
  "totalQuestionsAnswered": 0
}

*/
```

{% endtab %}
{% endtabs %}

### setUserProfile`(profile): Promise<Profile>`

Allow to set the user display information. Generally used to set the user name.&#x20;

{% tabs %}
{% tab title="Code" %}

```javascript
// You are not allowed to change the reserved fields like `points` or `bestScore`
const userProfile = {
  name: 'User', 
  code: 1234
}; 

SDK
  .quest
  .setUserProfile(userProfile)
  .then(profile => console.log(profile))
  .catch(err => console.error(err)); 
  
/* prints

{
  "userId": "user@stagecast.com",
  "name": "User",
  "code": 1234,
  "points": 52187,
  "bestScore": 52187,
  "momentId": "abc123",
  "prizes": null,
  "questionsAnswered": 0,
  "roundsPlayed": 0,
  "totalRoundsPlayed": 7,
  "totalQuestionsAnswered": 0
}

*/
```

{% endtab %}
{% endtabs %}

###

### playNewRound`(): Promise<Profile>`

This function allows a user to play another round of a quiz. It's **`points`** are set to 0.&#x20;

{% tabs %}
{% tab title="Code" %}

```javascript
SDK
  .quest
  .playNewRound()
  .then(myOwn => console.log(myOwn))
  .catch(err => console.error(err)); 
  
/* prints

{
  "userId": "user@stagecast.com",
  "name": "User#9265",
  "points": 0,
  "bestScore": 52187,
  "momentId": "abc123",
  "prizes": null,
  "questionsAnswered": 0,
  "roundsPlayed": 1,
  "totalRoundsPlayed": 7,
  "totalQuestionsAnswered": 0
}

*/
```

{% endtab %}
{% endtabs %}

{% hint style="warning" %}
This call should be made BEFORE the round gets played. This call will unlock the n questions a round allows.&#x20;
{% endhint %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://dev-stagecast.gitbook.io/moments-sdk/documentation/api-reference/quest-beta.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.