Guide d'API de rapports Kahoot!

Mise à jour

Tu te demandes comment utiliser l'API de rapport Kahoot! ? Voici tout ce que tu dois savoir pour commencer.

Accès rapides :

À propos de l'API de Kahoot 

L'API Kahoot est une API REST qui suit l'OpenAPI. Tu peux consulter toute la documentation de notre API, y compris les détails des ressources et des points de terminaison, sur https://results.kahoot.com/swagger/. 

Pour pouvoir faire des appels à l'API de Kahoot, ton entreprise devra disposer d'un accès autorisé. L'API est la meilleure solution pour les clients qui ont soit une équipe de données, soit des développeurs qui connaissent bien les API. Avec cette API, ton entreprise pourra accéder à toutes les données énumérées ci-dessous dans les 90 derniers jours après la fin du jeu. Nous horodatons nos données et prenons en charge les dates de début et de fin pour le moment où le client extrait les données de notre système. 

L'API de Kahoot rend compte des informations relatives au jeu, aux utilisateurs, aux participants, aux organisations et aux kahoots créés par l'organisation. Parfois, nos rapports sur la plateforme ne peuvent pas faire grand-chose. Pour les clients qui utilisent le produit fréquemment ou avec un grand nombre de participants, et qui veulent suivre leur activité, l'API est un excellent moyen de le faire de manière évolutive.

Comment accéder à l'API

L'autorisation de l'API est uniquement disponible pour les clients de certains plans de niveau supérieur. Contacte ton responsable de la réussite client si tu es intéressé par la mise à niveau ou le lancement du processus d'autorisation.

S'authentifier avec l'API

L'authentification pour l'API est réalisée par l'utilisation d'un jeton de porteur JWT qui doit être fourni dans l'en-tête Authentication de chaque demande à l'API. Les jetons sont limités dans le temps à une heure, après quoi un nouveau jeton doit être obtenu.

Pour obtenir un jeton, tu auras d'abord besoin d'un identifiant et d'un secret de client qui te seront fournis par ton responsable du succès client. Une fois que tu as ces informations d'identification, tu dois demander le jeton à notre serveur d'authentification comme décrit ci-dessous.

URL

https://access-2.kahoot.com/auth/realms/kahoot-api/protocol/openid-connect/token

Méthode Http

PUT

En-tête d'autorisation

Devrait fournir une rubrique d'autorisation de base en utilisant les informations d'identification fournies par kahoot.

En-tête Content-Type

application/x-www-form-urlencoded

Corps de la demande

grant_type=client_credentials

 

Un exemple de demande qui pourrait être faite avec curl est présenté ci-dessous :

curl --request POST \
--url https://access-2.kahoot.com/auth/realms/kahoot-api/protocol/openid-connect/token \
--header 'Autorisation : Basic <digest>' \
--header 'Content-Type : application/x-www-form-urlencoded' \
--data grant_type=client_credentials

 

La réponse à la demande aura la structure suivante :

{
"access_token" : "<token to use in api requests>",
"expires_in" : 3600,
"refresh_expires_in" : 0,
"token_type" : "Bearer",
"not-before-policy" : 0,
"scope" : "profil de messagerie"
}

 

Pour t'authentifier correctement auprès de l'API, tu dois utiliser la valeur de l'access_token dans la réponse ci-dessus comme jeton porteur dans tes demandes à l'API. Cela signifie que l'en-tête Authorization de toutes les demandes doit avoir la valeur sous la forme "Bearer : <token>". Si tu n'as pas correctement fourni un jeton valide à l'API, une réponse 401 sera renvoyée.

Glossaire

Terme

Description

Jeu en direct

Lorsqu'un kahoot est joué en personne.

Défi

Lorsqu'un kahoot est joué de manière asynchrone.

points

Valeur entière. Le nombre de points que le joueur a obtenu pour cette question.

réponses

Un ensemble de réponses soumises pour une question.

reçu, de temps d'au de réception

La réponse fournie à la question.

délai d'attente

Lorsqu'un utilisateur n'a pas fourni de réponse à une question.

Bloc

Les types de questions spécifiques sont toujours désignés par le terme "bloc", par exemple, le type de question Vrai ou Faux est appelé TrueFalseBlock et le type de question Brainstorm est désigné par BrainstormBlock.

kahoot

Le vrai kahoot. C'est différent d'un jeu ou d'une session de jeu (ce que nous appelons lorsque le kahoot est réellement joué).

jeu sur Kahoot!

Lorsque le kahoot est joué.

session de jeu

Une instance de jeu unique.

hôte

L'utilisateur qui a lancé le jeu.

version kahoot

Si les kahoots sont modifiés, nous stockons différentes versions de ce kahoot. Différentes versions d'un kahoot peuvent être jouées et donc avoir des réponses différentes enregistrées. La version du kahoot où 0 est indiqué n'est pas versionnée.

cours

Certains jeux sont liés à des cours, si c'est le cas, un identifiant de cours sera fourni.

Index des blocs - Kahoot

Indice auquel le jeu est apparu à l'origine dans le kahoot associé (basé sur 0).

Index des blocs - Jeu

Indice auquel le jeu est apparu pendant la session de jeu (basé sur 0).

Peut être différent de blockIndexInKahoot en cas d'utilisation d'un ordre aléatoire des questions.

questions

Liste des questions du kahoot.

Brainstorm (type de question)

Type de question ouverte où les participants soumettent des idées et votent.

Drop Pin (type de question)

Question sans points où les participants peuvent déposer des épingles sur une image.

Sondage (type de question)

Question sans points où les joueurs choisissent jusqu'à 6 options dans une question.

Quiz multi-sélection (type de question)

Donne aux joueurs plusieurs réponses à choisir dans une question.

Ouvert (type de question)

Question à laquelle les joueurs doivent répondre dans une réponse textuelle longue.

Puzzle (type de question)

Question où les joueurs mettent les réponses dans le bon ordre.

Slider (type de question)

Les participants devinent le bon nombre dans une fourchette.

Vrai Faux (type de question)

Les participants décident si une affirmation est vraie ou fausse.

Type Réponse (type de question)

Les participants répondent par un texte court.

Word Cloud (type de question)

Question qui recueille de courtes questions de sondage en forme libre.

Demandes communes - Guide pratique

Comment lister les participants d'un jeu

Qui est un "participant" ? 

Les étapes suivantes décrivent comment répertorier tous les joueurs qui sont entrés dans la partie. 

Sache que "rejoindre" n'est pas la même chose que "jouer activement". Il est possible de rejoindre le jeu et de ne répondre à aucune question en raison de problèmes de connexion ou de manque d'attention. Ces participants vont quand même être inclus dans les résultats. 

Trouve le jeu 

Invoque GET /v1/organisations/{organisationId}/games?limit={limit}&startedSince={date} pour répertorier tous les matchs joués dans ton organisation pendant une période donnée. Ajoute le paramètre de requête curseur au cas où une autre page de résultats serait disponible et nécessaire.

Un exemple de sortie contient une liste de sessions de jeu :

{
données : [
"gameSessionId" : "3c28c370-0407-416f-a44f-087715b4ea89", "hostUserId" : "70feec9e-1ee3-4e35-8d6b-0fe44d9f2358", "kahootIdentifier" : {
 "id" : "3c28c370-0407-416f-a44f-087715b4ea89", 
 "version" : 5 
},
"startTime" : 1667928438123,
}
],
curseur : "abcxyz"
}

Trouve la session dans les résultats et rappelle-toi qu'elle est gameSessionId. 

Liste des participants au jeu 

Invoque GET /v1/organisations/{organisationId}/jeux/{gameSessionId}/participants pour lister tous les participants qui ont rejoint le jeu.

Résultat de l'échantillon : 

[

{

"participantId" : 1234,

"nickname" : "Johnny",

"userId" : "f7e9a793-f223-4f2e-ad79-8bfa546a7180"

},

{

"participantId" : 4321,

"nickname" : "Robert",

"userId" : "a9555f0c-68b2-41b1-a540-49c34e15242e"

}

]

Quelle est la différence entre participantId et userId? 

  • participantId est un nombre entier et est toujours présent quelles que soient les options du jeu.
  • participantId identifie le joueur donné dans cette session de jeu uniquement. Le même participantId dans une session de jeu différente peut et fait généralement référence à une personne différente. 
  • userId n'est inclus que dans les jeux dont l'option Identificateur de joueur est activée. C'est à ce moment-là que les joueurs sont invités à fournir leurs informations d'identification, comme leur adresse e-mail, en plus de leur pseudo. Ou lorsqu'ils sont invités au jeu en utilisant leurs e-mails.
  • userId permet de suivre la même personne sur plusieurs sessions de jeu.

Comment obtenir l'adresse e-mail du participant 

Invoke GET /v1/organisations/{organisationId}/users/{userId} L'objet renvoyé contiendra la propriété email . 

Comment répertorier les participants qui ont obtenu au moins 80 % de questions justes 

Trouve le jeu

Voir la section sur la recherche du jeu. 

Trouve les informations sur le kahoot qui a été joué. Il comporte deux parties : 

  1. id - UUID référençant le kahoot qui a été joué
  1. version - le kahoot a peut-être été modifié par le créateur après que le jeu ait eu lieu. Chaque fois que cela se produit, la propriété version est incrémentée. Cela garantit que les réponses se réfèrent à des données correctes.  
{

// autres propriétés

"kahootIdentifier" : {

"id" : "3c28c370-0407-416f-a44f-087715b4ea89",

"version" : 5

},

}

Obtenir des participants

Voir la section sur la liste des participants.

Obtiens les données de kahoot 

Invoque GET /v1/organisations/{organisationId}/kahoots/{kahootId}/versions/{version} pour obtenir le kahoot avec des paramètres de requête basés sur les propriétés kahootIdentifier.id et kahootIdentifier.version . 

Le résultat va contenir toutes les questions (blocs) contenues dans le kahoot ainsi que les choix de réponses qui étaient à la disposition des participants, le cas échéant. Les questions et les choix de réponse seront référencés ultérieurement par les documents de réponse. 

Exemples de questions : 

{

"kahootIdentifier" : {

"id" : "3c28c370-0407-416f-a44f-087715b4ea89",

"version" : 5

},

"title" : "Titre du Kahoot",

"description" : "Ce kahoot porte sur ...",

"questions" : [

{

"contentType" : "CONTENT"

"blockIndex" : 0

"title" : "C'est la présentation de l'entreprise"

"description" : "Quelques contenus de diapositives"

},

{

"contentType" : "SINGLE_SELECT_QUIZ"

"blockIndex" : 1

"question" : "Qui est notre plus gros client ?" 

Les "choix" : [

{"answerText" : "Very Big Corp. of America", "correct" : faux},

{"answerText" : "Skynet", "correct" : vrai}

]

},

]

}

Obtiens toutes les réponses 

Invoque GET /v1/organisations/{organisationId}/jeux/{gameSessionId}/blocs/{blockIndex}/réponses en utilisant gameSessi onId obtenu lors de la recherche du jeu (voir la section trouver le jeu) et blockIndex étant l'index de la question dans le kahoot. Il faut itérer sur tous les blocs (questions) qui ont été joués, en excluant ceux qui n'étaient pas du tout des questions (contenu). diapositives). 

L'exemple suivant montre une réponse au deuxième bloc du kahoot qui était un quiz à sélection unique, où le participant s'est identifié avec parti cipantId=1234 (surnom "Johnny" comme dans l'exemple listant les participants) et a sélectionné le deuxième choix qui s'est avéré être correct. Nous pouvons également voir que le participant avec le surnom "Robert" n'a pas réussi à répondre à la question dans le délai imparti.

{

"blockIndexInKahoot" : 1

"réponses" : [

{

"participantId" : 1234,

"answerStatus" : "RECEIVED",

"answer" : {

"type" : "SINGLE_SELECT_QUIZ",

"choix" : 1,

"correct" : true,

"points" : 900

}

},

{

"participantId" : 4321,

"answerStatus" : "TIMEOUT"

},

]

}

Pour savoir quel était le choix et quel était le surnom du participant, il faut se référer aux données connexes de kahoot et aux données du participant mentionnées dans les sections précédentes. 

Et si 404 est renvoyé ? 

Les réponses pour un bloc donné peuvent manquer dans les cas suivants : 

  1. La question donnée (bloc) est de type CONTENU. "Répondre" à ces questions n'est pas bien défini. 
  2. Le jeu a été joué comme un devoir et aucun des participants n'a atteint cette question 3. 
  3. Il y a eu un problème de réseau pendant le jeu et la réponse n'a pas été enregistrée (cas rare, mais possible de se produire).

Dans tous les cas, les clients doivent être préparés au fait que les données de réponse peuvent manquer à cet endroit. 

Faire correspondre les réponses avec les participants 

Les réponses contiennent uniquement les liens vers les participants dont les détails sont contenus dans la charge utile de la réponse du point de terminaison séparé (voir la section "Liste des participants au jeu"). Ce lien est participantId propriété présente dans les deux charges utiles. 

Que signifie "réponse correcte" ? 

Dans le cas de certains types de questions, il existe une zone grise entre le statut de réponse "incorrecte" et "correcte".

Questions de quiz à sélection multiple 

CORRECT - le participant a sélectionné tous les bons choix et aucun des mauvais.

PARTIELLEMENT_CORRECT - le participant a sélectionné au moins un des bons choix et aucun des mauvais MAUVAIS - le participant a sélectionné au moins un des mauvais choix

Questions sur les curseurs 

CORRECT - le participant a sélectionné la bonne valeur sur le curseur

ALMOST_CORRECT - le participant a sélectionné une valeur qui n'était pas exacte, mais qui se trouvait dans la tolérance fixée par le créateur du kahoot WRONG - la valeur sélectionnée se trouvait en dehors de la plage de tolérance.

Toutes les autres questions 

Pour toutes les autres questions qui peuvent avoir des réponses justes ou fausses, il n'y a que deux choix : CORRECT et MAUVAIS.

Relation entre le temps écoulé et la bonne réponse 

Les objets ParticipantAnswer avec status égal à TIMEOUT n'auront pas la propriété answer , ils ne sont donc ni "corrects" ni "faux".  C'est à l'utilisateur de décider comment les traiter. On leur attribue toujours zéro point pendant le jeu.

Articles associés

Rapports

Articles associés

Rapports

0 commentaire

Vous devez vous connecter pour laisser un commentaire.