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.
| URL | https://access-2.kahoot.com/auth/realms/kahoot-api/protocol/openid-connect/token |
| Http Metode | PUT |
| Godkendelses Header | Skal give grundlæggende tilladelse overskrift ved hjælp af legitimationsoplysninger leveret af kahoot. |
| Indholdstype Header | applikation/x-www-form-urlenkodet |
| Nummer på anmodning | grant_type=client_credentials |
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
| Benævnelse | Varebeskrivelse |
| Live Spil | Når en kahoot spilles personligt. |
| Udfordring | Når en kahoot spilles asynkront. |
| point | Heltal værdi. Antallet af point spilleren fik for dette spørgsmål. |
| svar | Et sæt svar på et spørgsmål. |
| modtaget, timeout | Svaret er givet til spørgsmålet. |
| timeout | Når en bruger ikke gav et svar på et spørgsmål. |
| Blokér | Specifikke typer af spørgsmål omtales altid som 'blok' for eksempel - den sande eller falske spørgsmål type kaldes TrueFalseBlock og Brainstorm spørgsmål type kaldes BrainstormBlock. |
| kahoot | Den faktiske kahoot. Dette er anderledes end et spil eller spil session (hvad vi kalder når kahoot faktisk spilles). |
| spil | Når kahooten spilles. |
| spil session | En unik spilforekomst. |
| vært | Brugeren, der lancerede spillet. |
| kahoot version | Hvis kahoots er ændret, gemmer vi forskellige versioner af kahoot. Forskellige versioner af en kahoot kan spilles og har således forskellige svar gemt. Den version af kahoot, hvor 0 er angivet, er ikke versioneret. |
| kursus | Nogle spil er bundet til kurser, hvis dette er tilfældet, vil der være et kursus ID leveret. |
| Blok indeks - Kahoot | Indeks, hvor spillet oprindeligt dukkede op i den tilknyttede kahoot (0-baseret). |
| Blok indeks - Spil |
Indeks, hvor spillet dukkede op under spilsessionen (0-baseret). Kan være anderledes end blockIndexInKahoot i tilfælde af tilfældig rækkefølge af spørgsmål blev brugt. |
| spørgsmål | Liste over spørgsmål i kahooten. |
| Brainstorm (spørgsmålstype) | Open-ended spørgsmål type, hvor deltagerne indgiver ideer og stemme. |
| Drop Pin (spørgsmålstype) | Spørgsmål uden punkter, hvor deltagerne kan slippe stifter på et billede. |
| Afstemning (spørgsmålstype) | Spørgsmål uden point, hvor spillerne vælger op til 6 muligheder i et spørgsmål. |
| Multiselect Quiz (spørgsmålstype) | Giv spillere flere svar at vælge imellem i et spørgsmål. |
| Åben sluttet (spørgsmålstype) | Spørgsmål til spillere at besvare i en lang form tekst svar. |
| Puslespil (spørgsmålstype) | Spørgsmål, hvor spillerne sætter svar i den rigtige rækkefølge. |
| Skyder (spørgsmålstype) | Deltagerne gætter det korrekte tal i et område. |
| Sand Falsk (spørgsmålstype) | Deltagerne beslutter, om en erklæring er sand eller falsk. |
| Skriv svar (spørgsmålstype) | Deltagerne besvarer med en kort formulartekst. |
| Word Cloud (spørgsmålstype) | Spørgsmål der indsamler korte spørgsmål i fri form. |
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:
- ID - UUID refererer til kahoot der blev spillet
- 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:
- Givet spørgsmål (blok) er af typen INDHOLD. "Besvarelse" dem er ikke veldefinerede.
- Spillet blev spillet som en opgave, og ingen af deltagerne nåede det spørgsmål 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!
0 kommentarer
Log ind for at kommentere.