Veiledning om API-et for Kahoot!-rapporter

Lurer du på hvordan du bruker API-et for Kahoot!-rapporter Her er alt du trenger å vite for å komme i gang.

Snarveier:

• Om Kahoot API-et
• Slik får du tilgang til API-et
• Autentisering med API-et
• Ordliste
• Vanlige forespørsler – Brukerveiledning

Om Kahoot API-et 

Kahoot! API-et er et REST API som følger OpenAPI. Du kan se gjennom all API-dokumentasjonen inkludert detaljer om ressurser og endepunkter på  https://results.kahoot.com/swagger/. 

For å kunne påkalle Kahoot! API-et så trenger bedriften autorisert tilgang. API-et er best for kunder som har enten et datateam eller utviklere som kjenner til API-er. Med dette API-et vil bedriften din få tilgang til alle nedenstående data fra de siste 90 dagene etter at spillet er ferdig. Vi tidsstempler dataene våre og start- og sluttdatoer for brukerstøtte for tidsrommet kundene henter dataene fra systemet vårt. 

Kahoot! API-et rapporterer om informasjon som angår spillet, brukere, deltakere, organisasjoner og kahooter som ble opprettet av organisasjonen. Noen ganger er ikke rapporteringen vår om plattformen bred nok. For kunder som bruker produktet ofte eller med et høyt antall deltakere, og ønsker å spore aktiviteten deres, passer API-et perfekt til å gjøre dette i stor skala.

Slik får du tilgang til API-et

Autorisasjon av API-et er bare tilgjengelig for kunder med bestemte betalte abonnementer. Ta kontakt med kundekontakten din hvis du er interessert i enten å oppgradere eller starte godkjenningsprosessen.

Autentisering med API-et

Autentisering for API-et oppnås gjennom bruk av et JWT-token som skal oppgis i autentiserings-toppteksten for hver forespørsel til API-et. Tokener er tidsbegrenset til én time etter at et nytt token må innhentes.

For å skaffe et token må du først ha en klient-ID og et hemmelig spørsmål med svar, som du får fra kundekontakten din. Når du har disse opplysningene, må du be om tokenet fra vår autentiseringsserver som beskrevet nedenfor.

Nettadresse	https://access-2.kahoot.com/auth/realms/kahoot-api/protocol/openid-connect/token
Http-metode	PUT
Godkjenning-topptekst	Bør gi grunnleggende godkjenningstopptekst ved bruk av legitimasjonen fra kahoot.
Innholdstype-topptekst	application/x-www-form-urlencoded
Brødteksten til forespørselen	grant_type=client_credentials

 

Nedenfor vises et eksempel på en forespørsel som kan gjøres med «curl»:

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 forespørselen har følgende struktur:

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

 

For å sikre riktig godkjenning av API-et, må du bruke verdien av access_token i svaret ovenfor som et bærer-token i dine forespørsler til API-et. Dette betyr at Godkjenning-toppteksten i alle forespørsler bør ha verdien i form av «Bærer: <token>». Hvis du ikke har oppgitt et gyldig token til API-et, vil et 401-svar bli returnert.

Ordliste

Begrep	Beskrivelse
Livespill	Når en kahoot spilles live.
Utfordring	Når en kahoot spilles asynkront.
poeng	Heltallsverdi. Antall poeng spilleren fikk for dette spørsmålet.
svar	Et sett innsendte svar for et spørsmål.
mottatt, tidsavbrudd	Svaret som er gitt for spørsmålet.
tidsavbrudd	Når brukeren ikke oppgav et svar på et spørsmål.
Blokk	Spesifikke spørsmålstyper omtales alltid som en «blokk», for eksempel spørsmålstypen Sant eller usant kalles TrueFalseBlock og spørsmålstypen Idémyldring kalles BrainstormBlock.
kahoot	Selve kahooten. Dette er annerledes enn et spill eller et spilløkt (det vi kaller det når kahooten faktisk spilles).
kahooten.	Når kahooten spilles.
spilløkt	En unik spillinstans.
vert	Brukeren som startet spillet.
kahoot-versjon	Hvis kahootene blir endret, lagrer vi ulike versjoner av kahooten. Ulike versjoner av en kahoot kan spilles og dermed ha ulike svar lagret. Versjonen av kahooten hvor 0 er indikert, lagres ikke.
kurs	Noen spill er bundet til kurs, hvis dette er tilfelle oppgis det en kurs-ID.
Blokkindeks – Kahoot	Indeks som spillet opprinnelig dukket opp i den tilhørende kahooten (0-basert).
Blokkindeks – Spill	Indeks der spillet dukket opp under spilløkten (0-basert). Kan være annerledes enn blockIndexInKahoot i tilfelle tilfeldig rekkefølge av spørsmål ble brukt.
spørsmål	Liste over spørsmål i kahooten.
Idémyldring (spørsmålstype)	Åpent spørsmålstype der deltakerne sender inn ideer og stemmer på dem.
Fest nålen (spørsmålstype)	Spørsmål uten punkter hvor deltakerne kan feste nåler på et bilde.
Avstemning (spørsmålstype)	Spørsmål uten punkter der spillere velger opp til seks alternativer i et spørsmål.
Flervalg-quiz (spørsmålstype)	Gi spillere flere svar å velge fra i et spørsmål.
Åpent spørsmål (spørsmålstype)	Spørsmål til spillere som de svarer på i form av et lengre tekstsvar.
Rekkefølge (spørsmålstype)	Spørsmål der spillere setter svar i riktig rekkefølge.
Tallinje (spørsmålstype)	Deltakerne gjetter det riktige tallet i en rekkevidde.
Sant eller usant (spørsmålstype)	Deltakerne tar stilling til om et utsagn er sant eller usant.
Skriv svaret (spørsmålstype)	Deltagere svarer med en kort tekst.
Ordsky (spørsmålstype)	Spørsmål som samler inn korte avstemningsspørsmål.

Vanlige forespørsler – Brukerveiledning

• Slik viser du deltakere i et spill
• Hvem er en «deltaker»? 
• Finn spillet
• Hva er forskjellen mellom participantId og userId? 
• Slik får du deltakerens e-postadresse
• Slik viser du deltakere som har minst 80 % spørsmål rett
• Hva skjer hvis vi ser meldingen 404? 
• Matche svar med deltakere 
• Hva betyr «riktig svar»?
• Forholdet mellom tidsavbrudd og korrekte svar 

Slik viser du deltakere i et spill

Hvem er en «deltaker»? 

Følgende trinn beskriver hvordan man lister opp alle spillerne som har blitt med i spillet. 

Vær oppmerksom på at å «bli med» ikke er det samme som å «spille aktivt». Det er mulig å bli med i spillet og ikke svare på noen spørsmål på grunn av tilkoblingsproblemer eller at man rett og slett ikke la merke til dem. Slike deltakere blir likevel med i resultatene. 

Finn spillet 

Bruk GET /v1/organisations/{organisationId}/games?limit={limit}&startedSince={date} for å vise alle spillene som ble spilt i organisasjonen din i løpet av en gitt tidsperiode. Legg til markør-parameter i tilfelle en annen side med resultater er tilgjengelig og nødvendig.

Et eksempel vil inneholde en liste over spilløkter:

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

Finn økten i resultatene og husk at gameSessionId. 

Vis deltagerne i spillet 

Bruk GET /v1/organisations/{organisationId}/games/{gameSessionId}/participants for å vise alle deltakerne som har blitt med i spillet.

Eksempelresultat: 

[ 

 { 

 "participantId": 1234, 

 "nickname": "Johnny", 

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

 }, 

 { 

 "participantId": 4321, 

 "nickname": "Robert", 

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

 } 

]

Hva er forskjellen mellom participantId og userId? 

• participantId er et heltall og er alltid tilstede, uavhengig av spillalternativene.
• participantId identifiserer den angitte spilleren bare i løpet av den angitte spilløkten. Samme participantId i en annen spilløkt henviser som regel til en annen person. 
• userId er bare inkludert i spill der alternativet Spiller-ID er aktivert. Det er når spillerne blir bedt om å oppgi innloggingsinformasjon som e-post i tillegg til kallenavnet. Eller når de er invitert til spillet via e-post.
• userId gjør det mulig å spore samme person på tvers av flere spilløkter.

Slik får du deltakerens e-postadresse 

Bruk GET /v1/organisations/{organisationId}/users/{userId} Det returnerte objektet vil inneholde egenskapen e-post . 

Slik viser du deltakere som har minst 80 % spørsmål rett 

Finn spillet

Se delen om å finne spillet. 

Finn informasjon om kahooten som ble spilt. Den består av to deler: 

1. id – UUID henviser til kahooten som ble spilt

2. versjon – kahooten kan ha blitt redigert av oppretteren etter at spillet var ferdig. Hver gang det skjer, så øker versjonsegenskapen. Dette sikrer at svarene henviser til riktige data. 

{ 

 // other propperties 

 "kahootIdentifier": { 

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

 "version": 5 

 }, 

}

Hent deltakere

Se delen om hvordan du viser deltakerne.

Hent kahootdata 

Bruk GET /v1/organisations/{organisationId}/kahoots/{kahootId}/versions/{version} for å hente kahooten med spørringsparametere basert på egenskapene kahootIdentifier.id og kahootIdentifier.version . 

Resultatet skal inneholde alle spørsmål (blokker) i kahooten sammen med svarvalgene som var tilgjengelige for deltakerne (hvis det var aktuelt). Spørsmål og svarvalg skal senere refereres av svarsdokumentene. 

Eksempelspørsmål: 

{ 

 "kahootIdentifier": { 

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

 "version": 5 

 }, 

 "title": "Kahoot title", 

 "description": "This kahoot is about ...", 

 "questions": [ 

 { 

 "contentType": "CONTENT" 

 "blockIndex": 0 

 "title": "This is the company presentation" 

 "description": "Some slide contents" 

 }, 

 { 

 "contentType": "SINGLE_SELECT_QUIZ" 

 "blockIndex": 1 

 "question": «Hvem er vår største kunde?» 

 "choices": [ 

 {"answerText": «Veldig stort selskap i Norge», "correct":  false}, 

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

 ] 

 }, 

 ] 

}

Hent alle svar 

Bruk GET /v1/organisations/{organisationId}/games/{gameSessionId}/blocks/{blockIndex}/answers ved bruk av spillSessi onId innhentet når du leter etter spillet (se delen om å finne spillet) og blockIndex som er indeksen i spørsmålet i kahooten. Én må gjentas over alle blokkene (spørsmål) som ble spilt, unntatt de som ikke var spørsmål (innhold, dvs. lysbilder). 

Det følgende eksemplet viser svar på andre blokk i kahooten som var en enkel quiz, der deltakeren identifiserte med parti cipantId=1234 (kallenavn «Johnny» som i eksempelet over hvordan du viser deltakere) og valgte det andre valget som var riktig. Vi ser også at deltakeren med kallenavnet «Robert» ikke klarte å besvare spørsmålet innen fristen.

{ 

 "blockIndexInKahoot": 1 

 "answers": [ 

 { 

 "participantId": 1234, 

 "answerStatus": "RECEIVED", 

 "answer": { 

 "type": "SINGLE_SELECT_QUIZ", 

 "choice": 1, 

 "correct": true, 

 "points": 900 

 } 

 }, 

 { 

 "participantId": 4321, 

 "answerStatus": "TIMEOUT" 

 }, 

 ] 

}

For å vite hva som var valget og hva som var deltakerens kallenavn, må man henvise til relatert kahootdata og deltakernes data nevnt i tidligere deler. 

Hva skjer hvis vi ser meldingen 404? 

Det kan hende at svarene mangler for en gitt blokk i følgende tilfeller: 

1. Gitt spørsmål (blokk) er av typen CONTENT. Å «besvare» dem er ikke godt definert. 
2. Spillet ble spilt som en tildeling og ingen av deltakerne nådde spørsmål 3. 
3. Det oppstod et nettverksproblem under spillingen og svaret ble ikke lagret (sjeldent tilfelle, men det kan skje).

Uansett må klientene være forberedt på at svardataene kan mangle der. 

Matche svar med deltakere 

Svarene inneholder kun lenker til deltakerne som inneholder detaljer i et separat responsresultat for sluttpunktet (se delen «Vis deltagerne i spillet»). Den koblingen er participantId -egenskapen i begge resultatene. 

Hva betyr «riktig svar»? 

Når det gjelder enkelte spørsmålstyper, er det litt tvil mellom svarstatusen «feil» og «riktig».

Quizspørsmål med flere valgmuligheter 

CORRECT - deltakeren valgte alle riktige svarvalgene og ingen feil svarvalg 

PARTIAL_CORRECT – deltakeren valgte minst ett av de riktige svarvalgene og ingen feil svarvalg WRONG – deltakeren valgte minst ett feil svarvalg 

Spørsmål med tallinje 

CORRECT – deltakeren valgte riktig verdi på tallinjen 

ALMOST_CORRECT – deltakeren valgte en verdi som ikke var nøyaktig, men innenfor toleransen fastsatt av kahoot-oppretteren WRONG – den valgte verdien var utenfor toleranseområdet

Alle andre spørsmål 

For alle andre spørsmål som kan ha rett eller feil svar, finnes det bare to valg: CORRECT og WRONG.

Forholdet mellom tidsavbrudd og riktig svar 

ParticipantAnswer-objekter med status lik TIMEOUT skal ikke ha svar-egenskapen, så de er verken «riktig» eller «feil».  Det er opp til brukeren å bestemme hvordan de skal behandles. De får alltid null poeng i spillet.