How to use the Participant Activity Report APIs
This page provides an overview of Klaxoon activities, including quizzes, surveys, memos, and adventures, as well as the types of questions available in each activity. It also explains how to access activity reports using the Klaxoon API, including details on participants and results.
Main concepts
Using Klaxoon API you can build integrations to collect participation and result reports for Klaxoon activities. This first section describes the Klaxoon activities and type of questions available within these activities.
Klaxoon Activities
| Klaxoon activity | Description |
|---|---|
| Quiz | A Quiz can include up to 20 questions of different formats: single or multiple choice, fill in the blank, find the word, drag'n drop... 9 types of Quiz questions are available to be enhanced visually with photos or videos. With either a “free” or “question by question” mode participants must answer the question correctly in order to advance to the next one. |
| Survey | A Survey is a series of 1 to 20 questions that may be used to gauge participants' opinions, assess their level of knowledge or ask questions about a topic. 6 types of questions are available |
| Memo | A Memo is a set of 1 to 300 pages, quiz questions, and survey questions used to present ideas, images, and videos. The purpose of the questions is to ensure that participants have understood information or to ask their opinion. |
| Adventure | An Adventure is a sequence of 1 to 10 steps enabling participants to explore content in a fun environment. Each step consists of one or more quiz questions (9 types available), which may be introduced by a contents page if required (text, videos, and images). |
| Mission | A Mission is a sequence of 1 to 10 steps enabling participants to explore content independently in a fun environment. Each step consists of an activity – Quiz, Survey, or Memo. |
| Session | A Session is a collection of activities designed to encourage interactivity at your face-to-face or remote meetings. It can include Adventure, Board, Memo, Quiz and Survey. |
Two main families of questions can be found into these Klaxoon activities :
- Quiz questions : used in the Quiz, Adventure and Memo activities
- Survey questions : used in the Survey and Memo activities
Quiz questions
Available in Quiz, Adventure and Memo activities.
| Quizz question type | Description | Example |
|---|---|---|
| Single choice | Participants select one answer from several options. | Spot the odd one out. |
| Multiple choice | Participants select several answers from several options. | What are the safety instructions? |
| Drag'n drop image to text | Participants match an image (thumbnail) with a text. | Find the product names |
| Drag'n drop image to image | Participants match an image with another image. | Match these brands and their founders. |
| Find the word | Participants must enter a word or number in response to a question. | How many ... ? / In what year ... ? / What is the name of ... ? |
| Fill the gaps | Participants must enter words to fill in the gaps. | Enter the missing words. |
| Categorize | Participants turn over images to find pairs. | Match the images. |
| Sort into order | Participants sort items into order. | Sort the following from newest to oldest. |
Survey questions
Available in Survey and Memo Activities.
| Survey question type | Description | Example |
|---|---|---|
| Single choice | Participants select one answer from several options. | Yes/No? |
| Multiple choice question | Participants select several answers from several options. | Have you ever ... ? |
| Comment | Participants can enter any comments they wish (for open questions). | What positive aspects do you recall? |
| Rating | Participants award a score out of 5. You can enable the option allowing them to add a comment. | Score the item. |
| Sort into order | Participants must sort items into pre-defined categories. | Sort by order of preference. |
| Categorize | Participants must sort items into pre-defined categories. | Do you think these objectives should be achieved in the short or long term? |
To access Activity Reports from your application or service using the APIs you need to :
- Register your application. See the Create an App section.
- Provide users with a simple "Connect to Klaxoon" button for your application to be granted with Activity access right of the user. This can be done implementing the OAuth 2 authorization protocol for a Klaxoon users to authorize your application to read activities data.
User permissions
A Klaxoon user with access to an activity can either be host or participant with different rights :
Hosts
- List participants of the activity
- Retrieve participants results
Participants
- List participants of the activity
- Retrieve their own participant's details and results
Activities
An activity in Klaxoon is either a Quiz, a Survey, a Memo and Adventure. These activities can be listed using the following endpoints. It will return activities where the user is participant (not blocked) or the author.
Once the authorization flow is in place and a user granted access to your application the list or a specific activity available for this user can be retrieve using the following endpoints :
For each activity you get access to the following object
{
"id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"title": "Klaxoon activity title",
"description": "This is a Klaxoon activity",
"accessCode": "ABCDEFG",
"state": "draft",
"author": {
"id": "string"
},
"createdAt": "2024-02-20T16:51:14.482Z",
"updatedAt": "2024-02-20T16:51:14.482Z"
}
| Objects and Attributes | Description |
|---|---|
| id | Unique identifier for the activity |
| title | Title of the activity |
| description | Short description of the activity |
| accessCode | Unique access code use to join the activity in Klaxoon |
| state | Current activity state. Can be one of the followingdraft, published or closed |
| author | Author of the activity |
Participants
A participant is user who actually participated to your activity in Klaxoon.
For a given Klaxoon activity you can either retrieve participant details of the current user, a specific participant or access the full list of participants using the following endpoints.
For each participant you get access to the following object
{
"id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"username": "J.D",
"role": "host",
"user": {
"id": "yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyy",
"firstname": "John",
"lastname": "Doe",
"email": "[email protected]"
}
}
| Participant Object and Attributes | Description |
|---|---|
| id | ID of the participant. This ID is unique by Activity participation. |
| username | Username of the participant. Available if Join using a Nickname option is enabled on the activity. |
| role | Role of the participant in the activity. Can be one of the following host or participant |
| user | The user information of the participant (see user object details below) |
| User Object and Attributes | Description |
|---|---|
| id | Unique ID of the user. |
| firstname | First name of the participant. Available only if the participant is connected to his Klaxoon account when he join the activity. |
| lastname | Last name of the participant. Available only if the participant is connected to his Klaxoon account when he join the activity. |
| Email of the participant. Only available for the current user or for all participants if the API call made by the host of the activity. |
Results
Results associated with an activity can be included in the response alongside the participant resource. To indicate that you want to include result data you must specify the 'include' parameter with the value result when you request the Participant API endpoints.
Quiz Results
By using the include result parameter the Quiz result will be return in the payload as follow
{
"id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"username": "J.D",
"role": "host",
"user": {
"id": "yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyy",
"firstname": "John",
"lastname": "Doe",
"email": "[email protected]"
},
"result": {
"progression": 33.33,
"score": 33.33,
"successRate": 66.66,
"replays": 0,
"firstActionDate": "2020-07-24T09:00:00.000+0000",
"lastActionDate": "2020-07-24T09:00:00.000+0000",
"feedback": {
"comment": "string",
"rating": 5
}
}
}
| Result Object and Attributes | Description |
|---|---|
| progression | Percentage of questions answered by the participant out of the total number of questions in the Quiz |
| score | Score of the participant based on the whole Quiz (percentage) |
| successRate | Score of the participant based only on the questions already answered (percentage) |
| replays | The number of times the participant replayed the Quiz. The initial participation does not count as a Replay. |
| firstActionDate | Date of the first question answered by the participant |
| lastActionDate | Date of the last question answered by the participant |
| feedback | The feedback left by the participant at the end of the Quiz (see feedback object details below) |
| Feedback Object and Attributes | Description |
|---|---|
| comment | The comment left by the participant at the end of the Quiz |
| rating | The rating left by the participant at the end of the Quiz |
Survey Results
By using the include result parameter the Survey result will be return in the payload as follow
{
"id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"username": "J.D",
"role": "host",
"user": {
"id": "yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyy",
"firstname": "John",
"lastname": "Doe",
"email": "[email protected]"
},
"result": {
"progression": 33.33,
"answerRate": 33.33,
"firstActionDate": "2020-07-24T09:00:00.000+0000",
"lastActionDate": "2020-07-24T09:00:00.000+0000",
"feedback": {
"comment": "string",
"rating": 5
}
}
}
| Result Object and Attributes | Description |
|---|---|
| progression | Percentage of questions answered by the participant out of the total number of questions in the Survey |
| answerRate | Percentage of questions really answered (versus skipped) out of the total number of questions in the Survey |
| firstActionDate | Date of the first question answered by the participant |
| lastActionDate | Date of the last question answered by the participant |
| feedback | The feedback left by the participant at the end of the Survey (see feedback object details below) |
| Feedback Object and Attributes | Description |
|---|---|
| comment | The comment left by the participant at the end of the Survey |
| rating | The rating left by the participant at the end of the Survey |
Memo Results
By using the include result parameter the Memo result will be return in the payload as follow
{
"id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"username": "J.D",
"role": "host",
"user": {
"id": "yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyy",
"firstname": "John",
"lastname": "Doe",
"email": "[email protected]"
},
"result": {
"progression": 33.33,
"score": 33.33,
"successRate": 33.33,
"answerRate": 33.33,
"duration": 12345,
"firstActionDate": "2020-07-24T09:00:00.000+0000",
"lastActionDate": "2020-07-24T09:00:00.000+0000",
"feedback": {
"comment": "string",
"rating": 5
}
}
}
| Result Object and Attributes | Description |
|---|---|
| progression | Percentage pages (questions or simple pages) read by the participant out of the total number of pages in the Memo |
| score | Score of the participant based on the whole Memo (percentage) |
| successRate | Score of the participant based only on the questions already answered (percentage) |
| answerRate | Percentage of questions really answered (versus skipped) out of the total number of questions in the Memo |
| duration | Duration in seconds the participant spent reading the Memo (the timer is paused if the tab containing the memo is not active) |
| firstActionDate | Date of the first question answered or page read by the participant |
| lastActionDate | Date of the last question answered or page read by the participant |
| feedback object | The feedback left by the participant at the end of the Memo (see feedback object details below) |
| Feedback Object and Attributes | Description |
|---|---|
| comment | The comment left by the participant at the end of the Memo |
| rating | The rating left by the participant at the end of the Memo |
Adventure Results
By using the include result parameter the Adventure result will be return in the payload as follow
{
"id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"username": "J.D",
"role": "host",
"user": {
"id": "yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyy",
"firstname": "John",
"lastname": "Doe",
"email": "[email protected]"
},
"result": {
"progression": 33.33,
"points": 1000,
"successRate": 33.33,
"score": 33.33,
"replays": 2,
"firstActionDate": "2020-07-24T09:00:00.000+0000",
"lastActionDate": "2020-07-24T09:00:00.000+0000",
"feedback": {
"comment": "string",
"rating": 5
}
}
}
| Result Object and Attributes | Description |
|---|---|
| progression | Percentage of questions answered by the participant out of the total number of questions in the Adventure |
| points | Total points earned by the participant |
| score | Score of the participant based on the questions of the whole Adventure (percentage) |
| successRate | Score of the participant based only on questions already answered (percentage) |
| replays | The number of times the participant replayed the Adventure. The initial participation does not count as a Replay. |
| firstActionDate | Date of the first question answered by the participant |
| lastActionDate | Date of the last question answered by the participant |
| feedback object | The feedback left by the participant at the end of the Adventure (see feedback object details below) |
| Feedback Object and Attributes | Description |
|---|---|
| comment | The comment left by the participant at the end of the Adventure |
| rating | The rating left by the participant at the end of the Adventure |
Mission Results
By using the include result parameter the Mission result will be return in the payload as follow
{
"id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"username": "J.D",
"role": "host",
"user": {
"id": "yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyy",
"firstname": "John",
"lastname": "Doe",
"email": "[email protected]"
},
"result": {
"progression": 33.33,
"points": 1000,
"successRate": 33.33,
"score": 33.33,
"firstActionDate": "2020-07-24T09:00:00.000+0000",
"lastActionDate": "2020-07-24T09:00:00.000+0000",
"feedback": {
"comment": "string",
"rating": 5
}
}
}
| Result Object and Attributes | Description |
|---|---|
| progression | Percentage of steps completed by the participant out of the total number of steps in the Mission |
| points | Total points earned by the participant |
| score | Score of the participant based on the Quiz activity steps of the whole Mission (percentage) |
| successRate | Score of the participant based only on the Quiz activity steps already completed (percentage) |
| firstActionDate | Date of the first question answered or page read by the participant |
| lastActionDate | Date of the last question answered or page read by the participant |
| feedback object | The feedback left by the participant at the end of the Mission (see feedback object details below) |
| Feedback Object and Attributes | Description |
|---|---|
| comment | The comment left by the participant at the end of the Mission |
| rating | The rating left by the participant at the end of the Mission |
Session Results
By using the include result parameter the Session result will be return in the payload as follow
{
"id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"username": "J.D",
"role": "host",
"user": {
"id": "yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyy",
"firstname": "John",
"lastname": "Doe",
"email": "[email protected]"
},
"result": {
"points": 1000,
"score": 33.33,
"firstActionDate": "2020-07-24T09:00:00.000+0000",
"lastActionDate": "2020-07-24T09:00:00.000+0000",
"feedback": {
"comment": "string",
"rating": 5
}
}
}
| Result Object and Attributes | Description |
|---|---|
| points | Total points earned by the participant |
| score | Score of the participant based on the launched Quiz and Adventure activities of the Session (percentage) |
| firstActionDate | Date of the first question answered, timeline interaction or page read by the participant |
| lastActionDate | Date of the last question answered, timeline interaction or page read by the participant |
| feedback object | The feedback left by the participant at the end of the Session (see feedback object details below) |
| Feedback Object and Attributes | Description |
|---|---|
| comment | The comment left by the participant at the end of the Session |
| rating | The rating left by the participant at the end of the Session |
Updated about 2 months ago