Gids voor Kahoot! rapporten API

Vraag je je af hoe je Kahoot! rapporten API? Hier is alles wat je moet weten om te beginnen.

• Over de Kahoot API
• Toegang tot de API
• Authenticeren met de API
• Woordenlijst
• Veel voorkomende verzoeken - handleiding

Over de Kahoot API 

De Kahoot API is een REST API die OpenAPI volgt. Je kunt al onze API-documentatie bekijken, inclusief details van de bronnen en eindpunten op https://results.kahoot.com/swagger/. 

Om de Kahoot API te kunnen gebruiken, heeft uw bedrijf geautoriseerde toegang nodig. De API is het beste voor klanten die ofwel een datateam hebben, ofwel ontwikkelaars die bekend zijn met API's. Met deze API heeft je bedrijf toegang tot alle onderstaande gegevens van de laatste 90 dagen na afloop van het spel. Wij voorzien onze gegevens van een tijdstempel en ondersteunen begin- en einddata voor wanneer de klant de gegevens uit ons systeem haalt. 

De Kahoot-API biedt informatie over het spel, gebruikers, deelnemers, organisaties en de door de organisatie aangemaakte Kahoots. Soms kan onze berichtgeving op het platform maar zoveel doen. Voor klanten die het product vaak gebruiken of met een groot aantal deelnemers, en die hun activiteiten willen bijhouden, is de API een uitstekende manier om dat op schaal te doen.

Toegang tot de API

Autorisatie van de API is alleen beschikbaar voor klanten op bepaalde hoogste plannen. Neem contact op met je customer success manager als je geïnteresseerd bent in een upgrade of het in gang zetten van het autorisatieproces.

Authenticeren met de API

De authenticatie voor de API vindt plaats via een JWT-bearer-token, dat in de Authentication-header van elk verzoek aan de API moet worden opgenomen. Tokens zijn beperkt tot een uur; daarna moet er een nieuw token worden verkregen.

Om een token te verkrijgen, hebt u eerst een client-id en een geheim nodig, die u van uw customer success manager krijgt. Zodra u over deze inloggegevens beschikt, moet u het token bij onze authenticatieserver aanvragen zoals hieronder beschreven.

Een voorbeeldverzoek dat met curl zou kunnen worden gedaan staat hieronder:

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

Het antwoord van het verzoek zal de volgende structuur hebben:

{
"access_token": "<token te gebruiken in api requests>",
"expires_in": 3600,
"refresh_expires_in": 0,
"token_type": "Bearer",
"not-before-policy": 0,
"scope": "e-mailprofiel"
}

Om de API goed te authenticeren moet je de waarde van de access_token in het bovenstaande antwoord gebruiken als een bearer token in je verzoeken aan de API. Dit betekent dat de Authorization header van alle verzoeken de waarde "Bearer: <token>". Als je niet correct een geldig token aan de API hebt verstrekt wordt een 401 antwoord teruggestuurd.

Woordenlijst

Veel voorkomende verzoeken - handleiding

• Hoe maak je een lijst van deelnemers aan een spel
• Wie is een "deelnemer"? 
• Vind het spel
• Wat is het verschil tussen deelnemerId en userId? 
• Hoe kom je aan het e-mailadres van de deelnemer?
• Hoe maak je een lijst van deelnemers die minstens 80% van de vragen goed hadden
• Wat als er 404 terugkomt? 
• Antwoorden afstemmen op deelnemers 
• Wat betekent "juist antwoord"?
• Relatie tussen uitgetimed en juist antwoord

Hoe maak je een lijst van deelnemers aan een spel

Wie is een "deelnemer"? 

In de volgende stappen wordt uitgelegd hoe je alle spelers kunt weergeven die aan het spel hebben deelgenomen. 

Houd er rekening mee dat ‘lid worden’ niet hetzelfde is als ‘actief spelen’. Het is mogelijk aan het spel deel te nemen en geen vragen te beantwoorden vanwege verbindingsproblemen of niet opletten. Dergelijke deelnemers worden toch in de resultaten opgenomen. 

Vind het spel 

Vraag GET /v1/organisaties/{organisationId}/games?limit={limit}&startedSince={date} om een lijst te maken van alle wedstrijden die in je organisatie in een bepaald tijdsbestek zijn gespeeld. Voeg cursor query parameter toe voor het geval er nog een pagina met resultaten beschikbaar en nodig is.

Een voorbeeld van de uitvoer bevat een lijst met spelsessies:

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

Zoek de sessie in de resultaten en onthoud dat het gameSessionId. 

Lijst deelnemers aan het spel 

Roep GET /v1/organisaties/{organisationId}/games/{gameSessionId}/participanten op om een lijst te maken van alle deelnemers die aan het spel hebben meegedaan.

Voorbeeldresultaat: 

[

{

"participantId": 1234,

"nickname": "Johnny",

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

},

{

"participantId": 4321,

"nickname": "Robert",

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

}

]

Wat is het verschil tussen participantId en userId? 

• participantId is een geheel getal en is altijd aanwezig, ongeacht de spelopties.
• participantId identificeert een bepaalde speler alleen binnen deze spelsessie. Dezelfde participantId in een andere spelsessie kan verwijzen naar een andere persoon en doet dat meestal ook. 
• userId is alleen opgenomen in spellen met de Player Identifier optie ingeschakeld. Dat is wanneer de spelers gevraagd wordt om naast de bijnaam ook hun geloofsbrieven zoals e-mail op te geven. Of wanneer ze via hun e-mail worden uitgenodigd voor het spel.
• userId maakt het mogelijk om dezelfde persoon over meerdere spelsessies te volgen.

Hoe kom je aan het e-mailadres van de deelnemer? 

Invoke GET /v1/organisaties/{organisationId}/users/{userId} Het geretourneerde object zal email eigenschap bevatten. 

Hoe maak je een lijst van deelnemers die minstens 80% van de vragen goed hadden 

Vind het spel

Zie de paragraaf over het vinden van het spel. 

Zoek de informatie over de gespeelde kahoot. Het bestaat uit twee delen: 

1. id - UUID die verwijst naar de kahoot die werd gespeeld
2. versie - de kahoot kan door de maker bewerkt zijn nadat het spel plaatsvond. Telkens als dat gebeurt wordt de versie-eigenschap verhoogd. Dit garandeert dat de antwoorden verwijzen naar correcte gegevens. 

{

// other propperties

"kahootIdentifier": {

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

"version": 5

},

}

Krijg deelnemers

Zie het gedeelte over de opsomming van de deelnemers.

Krijg kahoot gegevens 

Roep GET /v1/organisaties/{organisationId}/kahoots/{kahootId}/versies/{version} op om de kahoot te krijgen met query parameters gebaseerd op kahootIdentifier.id en kahootIdentifier.version eigenschappen. 

Het resultaat zal alle vragen (blokken) bevatten die in de Kahoot voorkomen, samen met de antwoordopties die, indien van toepassing, aan de deelnemers ter beschikking stonden. Naar vragen en antwoordkeuzen wordt later verwezen in de antwoorddocumenten. 

Voorbeeldvragen: 

{

"kahootIdentifier": {

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

"version": 5

},

"title": "Kahoot title",

"description": "Deze kahoot gaat over ...",

"vragen": [

{

"contentType": "CONTENT"

"blockIndex": 0

"title": "Dit is de bedrijfspresentatie"

"description": "Some slide contents"

},

{

"contentType": "SINGLE_SELECT_QUIZ"

"blockIndex": 1

"vraag": "Wie is onze grootste klant?" 

 "keuzes": [

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

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

]

},

]

}

Krijg alle antwoorden 

Roep GET /v1/organisaties/{organisationId}/games/{gameSessionId}/blocks/{blockIndex}/answers op met behulp van gameSessi onId verkregen bij het zoeken naar het spel (zie sectie vind spel) en blockIndex zijnde index van de vraag in de kahoot. Men moet itereren over alle blokken (vragen) die gespeeld werden, met uitsluiting van de blokken die helemaal geen vragen waren (inhoud aka. dia's). 

Het volgende voorbeeld toont een antwoord op het tweede blok van de Kahoot, een quiz met één antwoordoptie, waarbij de deelnemer met participantId=1234 (bijnaam “Johnny”, zoals in het voorbeeld met de lijst van deelnemers) de tweede optie selecteerde, die toevallig het juiste antwoord was. We zien ook dat de deelnemer met de bijnaam "Robert" er niet in slaagde de vraag binnen de tijd te beantwoorden.

{

"blockIndexInKahoot": 1

"antwoorden": [

{

"participantId": 1234,

"answerStatus": "RECEIVED",

"answer": {

"type": "SINGLE_SELECT_QUIZ",

"choice": 1,

"correct": true,

"punten": 900 }



},

{

"participantId": 4321,

"answerStatus": "TIMEOUT"

},

]

}

Om te weten wat de keuze was en wat de bijnaam van de deelnemer was, moet men verwijzen naar de gerelateerde kahoot gegevens en de deelnemersgegevens die in de vorige paragrafen zijn genoemd. 

Wat als er 404 terugkomt? 

De antwoorden voor een bepaald blok kunnen ontbreken in de volgende gevallen: 

1. Gegeven vraag (blok) is van het type CONTENT. Het "beantwoorden" ervan is niet goed gedefinieerd. 
2. Het spel werd als opdracht gespeeld en geen van de deelnemers bereikte die vraag 3. 
3. Er was een netwerkprobleem tijdens de gameplay en het antwoord werd niet opgeslagen (zeldzaam geval, maar kan gebeuren).

In elk geval moeten de klanten erop voorbereid zijn dat de antwoordgegevens daar kunnen ontbreken. 

Antwoorden afstemmen op deelnemers 

Antwoorden bevatten alleen de links naar de deelnemers waarvan de details in de aparte payload van het eindpunt staan (zie de paragraaf "Lijst deelnemers van het spel"). Die link is participantId eigenschap aanwezig in beide payloads. 

Wat betekent "juist antwoord"? 

Bij sommige typen vragen bestaat er een grijs gebied tussen de status "onjuist" en "juist" antwoord.

Quizvragen met meerdere antwoordmogelijkheden 

JUIST - de deelnemer heeft alle juiste antwoorden geselecteerd en geen van de foute 

GEDEELTELIJK_CORRECT - de deelnemer heeft ten minste één van de juiste antwoorden geselecteerd en geen van de foute FOUT - de deelnemer heeft ten minste één van de foute antwoorden gekozen 

Vragen met schuifbalk 

JUIST - de deelnemer heeft de juiste waarde op de schuifbalk geselecteerd 

BIJNA_JUIST - de deelnemer heeft een waarde geselecteerd die niet exact was, maar wel binnen de door de Kahoot-maker ingestelde tolerantie lag FOUT - de geselecteerde waarde lag buiten het tolerantiebereik

Alle overige vragen 

Voor alle andere vragen die wel juiste of foute antwoorden hebben, zijn er slechts twee keuzes: JUIST en FOUT.

Verband tussen uitgetimed en juist antwoord 

ParticipantAnswer objecten met status gelijk aan TIMEOUT krijgen geen antwoord eigenschap, zodat ze noch "juist" noch "fout" zijn.  Het is aan de gebruiker om te beslissen hoe hij ermee omgaat. Ze krijgen tijdens het spel altijd nul punten toegewezen.

De API-gegevens weergeven

Er zijn veel manieren om geëxtraheerde API-gegevens te presenteren. Hier is een voorbeeld van Kahoot! gegevens gevisualiseerd in Power BI.

Vond je dit nuttig? Abonneer je op ons Youtube-kanaal voor meer tips en Kahoot! handleidingen!