> For the complete documentation index, see [llms.txt](https://dev-stagecast.gitbook.io/moments-sdk/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://dev-stagecast.gitbook.io/moments-sdk/documentation/api-reference/quiz.md).

# 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 %}