# Quiz (beta)

## Introduction

If you are implementing a Quiz, you can take advantage of the quiz API:s. These offer a set of utilities to create users, fetch and answer questions 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 **`quiz`** plugin to the list of plugins in your **`manifest.json`**.

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

## API Docs

### `setContext(quizId:string): Promise<Quiz>`

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

**Params**

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

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

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

SDK.quiz.setContext(quizId) 
```

{% endtab %}
{% endtabs %}

### `getQuiz(): Promise<Quiz>`

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

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

{
  "id": "abc123",
  "title": "Test Quiz",
  "event": "abc123",
  "seriesDuration": 180000,
  "questionDuration": 20000,
  "questionCount": 5,
  "prizesPerSeries": 1,
  "repeat": true,
  "questionsPerRound": 3,
  "maxRoundsPerSeries": 200,
  "seriesPlayed": 388
}

*/
```

{% endtab %}
{% endtabs %}

### getQuestion`(id): Promise<Question>`

**Params**

* **`id`**: the question id;

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

```javascript
SDK
  .quiz
  .getQuestion(1)
  .then(question => console.log(question))
  .catch(err => console.error(err)); 
  
  
/* prints
{
  "question": {
    "image": "https://tomaszjanickiphoto.co.uk/wp-content/gallery/scotland/DSC_9815-Panox_01.JPG",
    "text": "A question with image."
  },
  "choices": [{
    "type": "text",
    "value": "Answer 1"
  }, {
    "type": "text",
    "value": "Answer 2"
  }, {
    "type": "text",
    "value": "Answer 3"
  }],
  "hash": "Zi50ZXN0ZXJAc3RhZ2VjYXN0LmNvbTo5RkY3MTA2QS1BQ0I1LTQyOTYtOEVFQi1ENDBDQzQ5NjU4MDc6NDoxNTkxMjgwMjY4OTQ5",
  "group": "work"
}
*/
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
Make sure to load the question when you need it. This is important as the backend computes the points based on the question fetch timestamp.
{% endhint %}

### answerQuestion`(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
  .quiz
  .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
  .quiz
  .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
  .quiz
  .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/quiz.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.