Guide til Kahoot! rapporter API

Spekulerer på, hvordan man bruger Kahoot! rapporterer API? Her er alt hvad du behøver at vide for at komme i gang.

Genveje:

• Om Kahoot API
• Sådan får du adgang til API
• Godkender med API
• Glossary
• Almindelige Anmodninger - Sådan Guide

Om Kahoot API 

Kahoot API er en REST API, der følger OpenAPI. Du kan gennemse al vores API-dokumentation, herunder oplysninger om ressourcerne og endepunkterne på https://results.kahoot.com/swagger/. 

For at foretage opkald til Kahoot API din virksomhed vil kræve autoriseret adgang. API er bedst for kunder, der har enten et data-team eller udviklere, der er fortrolige med API'er. Med denne API vil din virksomhed kunne få adgang til alle nedenstående data inden for de sidste 90 dage efter spillets afslutning. Vi tidsstempler vores data og support start- og slutdatoer for, hvornår kunden trækker data fra vores system. 

Kahoot API rapporterer om oplysninger vedrørende spillet, brugere, deltagere, organisationer og kahoots skabt af organisationen. Nogle gange kan vores rapportering på platformen kun gøre så meget. For kunder, der bruger produktet ofte eller med et højt antal deltagere, og ønsker at spore deres aktivitet, API er en fantastisk måde at gøre det skalerbart.

Sådan får du adgang til API

Godkendelse af API er kun tilgængelig for kunder på visse højest niveau-planer. Nå ud til din kunde succes manager, hvis du er interesseret i enten at opgradere eller indlede autorisationsprocessen.

Godkender med API

Autentificering af API'en opnås ved brug af en JWT-bærer token, som bør gives i godkendelsesoverskriften for hver anmodning til API'en. Tokens er tidsbegrænset til en time, hvorefter en ny token skal opnås.

For at få en token skal du først bruge en klient id og hemmelighed, som vil blive leveret af din kunde succes manager. Når du har disse legitimationsoplysninger skal du anmode om token fra vores autentificering server som beskrevet nedenfor.

Et eksempel anmodning, der kunne foretages med krølle er vist nedenfor:

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

Svaret fra anmodningen vil have følgende struktur:

{
"access_token": "<token til brug i api-anmodninger>",
"expires_in": 3600,
"refresh_expires_in": 0,
"token_type": "Bearer",
"not-before-policy": 0,
"scope": "email profile"
}

For korrekt autentificering til API skal du bruge værdien af access_token i ovenstående svar som en bærer token i dine anmodninger til API. Det betyder, at godkendelses overskrift for alle anmodninger skal have værdien i form af »Bærer: <token>«. Hvis du ikke har leveret et gyldigt token til API vil et 401 svar blive returneret.

Glossary

Almindelige Anmodninger - Sådan Guide

• Sådan listes deltagere i et spil
• Hvem er en ”deltager”? 
• Find spillet
• Hvad er forskellen mellem deltagerId og brugerId? 
• Sådan får du deltagerens e-mailadresse
• Hvordan listes deltagere, der fik mindst 80% spørgsmål ret
• Hvad hvis 404 er returneret? 
• Matchende svar med deltagere 
• Hvad betyder ”rigtigt svar”?
• Forholdet mellem udskudt tid og korrekt svar

Sådan listes deltagere i et spil

Hvem er en ”deltager”? 

De følgende trin beskriver, hvordan man kan liste alle spillere, der deltog i spillet. 

Bemærk venligst, at “optagelse” ikke er det samme som “aktivt spil”. Det er muligt at deltage i spillet og ikke besvare spørgsmål på grund af forbindelsesproblemer eller ikke være opmærksom. Sådanne deltagere vil stadig være med i resultaterne. 

Find spillet 

Start FÅ /v1/organisationer/{organisationId}/games? imit={limit}&startedSince={date} for at liste alle spil spillet i din organisation i en given tidsramme. Tilføj cursor query parameter i tilfælde af en anden side af resultater er tilgængelig og nødvendig.

Et eksempel på output vil indeholde en liste over spilsessioner:

{
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"
}

Find sessionen i resultaterne, og husk at det er gameSessionId. 

Liste deltagere i spillet 

Start GET /v1/organisations/{organisationId}/games/{gameSessionId}/participants for at liste alle deltagere som kom med i spillet.

Resultater af prøven: 

[

{

"participantId": 1234,

"kaldenavn": "Johnny",

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

},

{

"participantId": 4321,

"nickname": "Robert",

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

}

]

Hvad er forskellen mellem participantId og userId? 

• participantId er et heltal og er altid til stede uanset spilmulighederne.
• participantId identificerer kun den givne spiller i denne spilsession. Samme participantId i en anden spilsession kan og refererer normalt til en anden person. 
• userId er kun inkluderet i spil med Player Identifier valgmulighed aktiveret. Det er, når spillerne er bedt om at give deres legitimationsoplysninger såsom e-mail i tillæg til øgenavnet. Eller når de inviteres til spillet ved hjælp af deres e-mails.
• userId gør det muligt at spore den samme person på tværs af flere spilsessioner.

Sådan får du deltagerens e-mailadresse 

Start FÅ /v1/organisations/{organisationId}/users/{userId} Den returnerede objekt vil indeholde e-mail ejendom. 

Hvordan listes deltagere, der fik mindst 80% spørgsmål ret 

Find spillet

Se afsnittet om at finde spillet. 

Find oplysningerne om den kahoot der blev spillet. Det har to dele: 

1. ID - UUID refererer til kahoot der blev spillet

2. version - kahooten kan være blevet redigeret af skaberen efter spillet fandt sted. Hver gang, der sker, det får versionsegenskaben øget. Dette sikrer, at svarene refererer til korrekte data. 

{

// other propperties

"kahootIdentifier": {

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

"version": 5

},

}

Get participants

Se afsnittet om optagelse af deltagerne.

Hent kahoot- data 

Start GET /v1/organisations/{organisationId}/kahoots/{kahootId}/versions/{version} for at få kahooten med forespørgselsparametre baseret på kahootIdentifier. d og kahootIdentifier.version egenskaber. 

Resultatet vil indeholde alle spørgsmål (blokke) indeholdt i kahooten sammen med de svar valg, der var tilgængelige for deltagerne, hvis relevant. Spørgsmål og svar valg vil senere blive henvist til svardokumenterne. 

Eksempel spørgsmål: 

{

"kahootIdentifier": {

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

"version": 5

},

"title": "Kahoot title",

"description": "Denne kahoot handler om ...",

"questions": [

{

"contentType": "CONTENT"

"blockIndex": 0

"title": "Dette er virksomhedens præsentation"

"description": "Nogle dias' indhold"

},

{

"contentType": "SINGLE_SELECT_QUIZ"

"blockIndex": 1

"question": "Hvem er vores største kunde?" 

 "choices": [

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

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

]

},

]

}

Få alle svar 

Start FÅ /v1/organisationer/{organisationId}/games/{gameSessionId}/blocks/{blockIndex}/answers med gameSessi onId opnået når du leder efter spillet (se afsnittet find spil) og blockIndex er indeks over spørgsmålet i kahooten. Man er nødt til at iterere over alle blokke (spørgsmål), der blev spillet, eksklusive dem, der ikke var spørgsmål overhovedet (indhold aka. dias). 

Følgende eksempel viser et svar på den anden blok af kahoot, som var en enkelt udvalgt quiz, hvor deltageren identificerede med parti cipantId=1234 (Nickname “Johnny” som i notering deltagerne eksempel) og valgte det andet valg, der tilfældigvis var korrekt. Vi kan også se, at deltageren med kaldenavnet “Robert” ikke formår at besvare spørgsmålet inden for tidsfristen.

{

"blockIndexInKahoot": 1

"answers": [

{

"participantId": 1234,

"answerStatus": "RECEIVED",

"answer": {

"type": "SINGLE_SELECT_QUIZ",

"choice": 1,

"correct": true,

"points": 900

}

},

{

"participantId": 4321,

"answerStatus": "TIMEOUT"

},

]

}

For at vide, hvad der var valget, og hvad der var deltagerens kaldenavn man har brug for at henvise til relaterede kahoot data og deltagerens data nævnt i tidligere afsnit. 

Hvad hvis 404 er returneret? 

Svarene for en given blok kan mangle i følgende tilfælde: 

1. Givet spørgsmål (blok) er af typen INDHOLD. "Besvarelse" dem er ikke veldefinerede. 
2. Spillet blev spillet som en opgave, og ingen af deltagerne nåede det spørgsmål 3. 
3. Der var et netværksproblem under gameplayet og svaret blev ikke gemt (sjældne tilfælde, men muligt at ske).

Under alle omstændigheder skal kunderne være forberedt på, at svaret data kan mangle der. 

Matchende svar med deltagere 

Svarene indeholder kun links til de deltagere, hvis detaljer er indeholdt i separat endpoints respons nyttelast (se “List participants of the game” sektion). Dette link er participantId ejendom til stede i begge nyttelast. 

Hvad betyder ”rigtigt svar”? 

I tilfælde af nogle spørgsmål typer, der findes nogle grå område mellem “forkert” og “korrekt” svar status.

Multiple-select quiz spørgsmål 

KORREKT - deltageren valgte alle korrekte valg og ingen af de forkerte

PARTIALLY_CORRECT - deltageren valgte mindst et af de rigtige valg og ingen af de forkerte WRONG - deltageren valgte mindst et af de forkerte valg

Slider spørgsmål 

KORREKT - deltageren valgte den korrekte værdi på skyderen

ALMOST_CORRECT - deltageren valgte en værdi, der ikke var præcis, men inden for den tolerance, der er fastsat af kahoot-skaberen WRONG - den valgte værdi lå uden for tolerance-området

Alle andre spørgsmål 

For alle andre spørgsmål, der kan har rigtige eller forkerte svar, er der kun to valgmuligheder: RIGTIGT og FORKERT.

Forholdet mellem timed-out og korrekt svar 

DeltagerSvar objekter med status lig med TID vil ikke have svar ejendom, så de hverken er "korrekte" eller "forkerte".  Det er op til brugeren at beslutte, hvordan man skal behandle dem. De er altid tildelt nul point i løbet af spillet.

Præsentation af API-data.

Der er mange måder at præsentere udtrukne API-data på. Her er et eksempel på Kahoot! data visualiseret i Power BI.

💡 Fandt du dette nyttigt? Abonner på vores Youtube-kanal for at få flere tips og Kahoot! tutorials!