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.

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 til bruk i api-forespørsler>",
"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

Vanlige forespørsler – Brukerveiledning

• Slik viser du deltakere i et spill
• Hvem er en «deltaker»? 
• Finn spillet
• Hva er forskjellen mellom deltakerId 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 utgått tid og riktig 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 på utdata 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,

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

{

// andre 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": "Denne kahoot handler om ...",

"questions": [

{

"contentType": "CONTENT"

"blockIndex": 0

"title": "Dette er selskapets presentasjon"

"description": "Some slide contents"

},

{

"contentType": "SINGLE_SELECT_QUIZ"

"blockIndex": 1

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

 "choices": [

{"answerText": "Very Big Corp. of America", "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 kan ha riktige eller gale svar, er det bare to valg: RIKTIG og FEIL.

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.

Presentasjon av API-data.

Det finnes mange måter å presentere API-data på. Her er et eksempel på Kahoot! data visualisert i Power BI.

💡 Fant du dette nyttig? Abonner på Youtube-kanalen vår for flere tips og Kahoot! opplæringsprogrammer!