Gids voor Kahoot! rapporten API

Bijgewerkt

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

Nuttige links:

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 aan te roepen heeft je 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 rapporteert over informatie met betrekking tot het spel, gebruikers, deelnemers, organisaties en kahoots die door de organisatie zijn gemaakt. Soms kan onze berichtgeving op het platform maar zoveel doen. Voor klanten die het product vaak of met een groot aantal deelnemers gebruiken, en hun activiteit willen bijhouden, is de API een geweldige manier om dat schaalbaar 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

Authenticatie voor de API wordt bereikt door het gebruik van een JWT bearer token dat in de Authentication header van elk verzoek aan de API moet worden verstrekt. Tokens zijn beperkt tot een uur, waarna een nieuwe token moet worden verkregen.

Om een token te verkrijgen heb je eerst een client id en secret nodig, die je krijgt van je customer success manager. Zodra je deze gegevens hebt, moet je het token aanvragen bij onze authenticatieserver, zoals hieronder beschreven.

URL

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

Http Methode

PUT

Machtigingsheader

Moet basis autorisatie rubriek geven met behulp van de door kahoot verstrekte credentials.

Inhoud-Type Kop

application/x-www-form-urlencoded

Inhoud van het verzoek

grant_type=client_credentials

 

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 <digest>' \
--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 to use 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

Term

Beschrijving

Live spel

Wanneer een kahoot persoonlijk wordt gespeeld.

Uitdaging

Wanneer een kahoot asynchroon wordt afgespeeld.

punten

Integer waarde. Het aantal punten dat de speler voor deze vraag kreeg.

antwoorden

Een reeks ingediende antwoorden voor een vraag.

ontvangen, time-out

Het gegeven antwoord op de vraag.

time-out

Als een gebruiker geen antwoord gaf op een vraag.

Blok

Specifieke typen vragen worden altijd aangeduid als "blok" bijvoorbeeld - het Waar of Onwaar vraagtype heet TrueFalseBlock en het Brainstorm vraagtype heet BrainstormBlock.

kahoot

De eigenlijke kahoot. Dit is anders dan een spel of spelsessie (wat we noemen als de kahoot daadwerkelijk gespeeld wordt).

kunt toevoegen

Wanneer de kahoot wordt gespeeld.

spelsessie

Een unieke spelinstantie.

presentator

De gebruiker die het spel lanceerde.

kahoot versie

Als kahoots gewijzigd worden, slaan we verschillende versies van die kahoot op. Er kunnen verschillende versies van een kahoot worden gespeeld en dus verschillende antwoorden worden opgeslagen. De versie van de kahoot waar 0 staat aangegeven is niet geversioneerd.

cursus

Sommige spellen zijn gebonden aan cursussen, als dit het geval is wordt er een cursus-ID verstrekt.

Blokindex - Kahoot

Index waarop het spel oorspronkelijk verscheen in de bijbehorende kahoot (op 0 gebaseerd).

Blokindex - Spel

Index waarop het spel tijdens de speelsessie verscheen (op 0 gebaseerd).

Kan anders zijn dan blockIndexInKahoot als een willekeurige volgorde van vragen is gebruikt.

vragen

Lijst van vragen in de kahoot.

Brainstorm (vraagtype)

Type open vraag waarbij deelnemers ideeën aandragen en stemmen.

Drop Pin (vraag type)

Vraag zonder punten waar deelnemers spelden op een afbeelding kunnen laten vallen.

Poll (vraagtype)

Vraag zonder punten waarbij de spelers maximaal 6 opties in een vraag kiezen.

Multiselect Quiz (vraagtype)

Geef de spelers verschillende antwoorden waaruit ze in een vraag kunnen kiezen.

Open vragen)

Vraag voor de spelers om te beantwoorden in een lang tekstantwoord.

Puzzel (vraagtype)

Vraag waarbij de spelers de antwoorden in de juiste volgorde zetten.

Schuifregelaar (vraagtype)

De deelnemers raden het juiste getal in een reeks.

Waar fout (vraagtype)

De deelnemers beslissen of een uitspraak waar of onwaar is.

Type Antwoord (vraagtype)

Deelnemers antwoorden met een korte formuliertekst.

Woordwolk (vraagtype)

Vraag die korte vrije-vorm enquêtevragen verzamelt.

Veel voorkomende verzoeken - handleiding

Hoe maak je een lijst van deelnemers aan een spel

Wie is een "deelnemer"? 

De volgende stappen beschrijven hoe je een lijst maakt van alle spelers die aan het spel hebben meegedaan. 

Merk op dat "meedoen" 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 voorbeelduitvoer bevat een lijst van spelsessies:

{
gegevens: [
"gameSessionId": "3c28c370-0407-416f-a44f-087715b4ea89", "hostUserId": "70feec9e-1ee3-4e35-8d6b-0fe44d9f2358", "kahootIdentifier": {
 "id": "3c28c370-0407-416f-a44f-087715b4ea89", 
 "versie": 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
  1. 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",

"versie": 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) van de kahoot bevatten naast de antwoordkeuzes die de deelnemers ter beschikking stonden, indien van toepassing. 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 content"

},

{

"contentType": "SINGLE_SELECT_QUIZ"

"blockIndex": 1

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

"keuzes": [

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

{"answerText": "Skynet", "correct": waar}.

]

},

]

}

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 dat een single select quiz was, waarbij de deelnemer zich identificeerde met parti cipantId=1234 (bijnaam "Johnny" zoals in het voorbeeld listing participants) en de tweede keuze selecteerde die toevallig juist 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

} }, { "DEELNEMER": TRUE, "PUNTEN":.

},

{

"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.

Multiple-select quizvragen 

CORRECT - de deelnemer selecteerde alle juiste keuzes en geen van de verkeerde

PARTIALLY_CORRECT - de deelnemer selecteerde ten minste één van de juiste keuzes en geen van de verkeerde keuzes WRONG - de deelnemer selecteerde ten minste één van de verkeerde keuzes

Schuifvragen 

CORRECT - de deelnemer selecteerde de juiste waarde op het schuifje

ALMOST_CORRECT - de deelnemer selecteerde een waarde die niet exact was, maar binnen de door de maker van de kahoot ingestelde tolerantie viel WRONG - de geselecteerde waarde lag buiten het tolerantiebereik

Alle andere vragen 

Voor alle andere vragen die goede of foute antwoorden kunnen hebben, zijn er slechts twee keuzes: CORRECT en WRONG.

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.

Was dit artikel nuttig?
Aantal gebruikers dat dit nuttig vond: 1 van 2

Kun je niet vinden wat je zoekt? Ons team helpt je graag!

Verwante artikelen

Rapporten

Verwante artikelen

Rapporten

0 opmerkingen

U moet u aanmelden om een opmerking te plaatsen.