Guide till Kahoot! rapporterar API

Undrar hur man använder Kahoot! rapporterar API? Här är allt du behöver veta för att komma igång.

Genvägar:

• Om Kahoot API
• Hur man får tillgång till API:et
• Autentiserar med API:et
• Glossary
• Vanliga förfrågningar - Hur man vägleder

Om Kahoot API 

Kahoot API är ett REST API som följer OpenAPI. Du kan granska all vår API-dokumentation inklusive detaljer om resurser och slutpunkter på https://results.kahoot.com/swagger/. 

För att ringa samtal till Kahoot API ditt företag kommer att kräva auktoriserad åtkomst. API är bäst för kunder som har antingen en datateam eller utvecklare som är bekanta med API:er. Med detta API kommer ditt företag att kunna komma åt alla data som anges nedan inom de senaste 90 dagarna efter spelets slut. Vi timestamp våra data och support start- och slutdatum för när kunden drar data från vårt system. 

Kahoot API rapporterar om information som hänför sig till spelet, användare, deltagare, organisationer och kahoots som skapats av organisationen. Ibland kan vår rapportering på plattformen bara göra så mycket. För kunder som använder produkten ofta eller med ett stort antal deltagare, och vill spåra sin aktivitet, API är ett bra sätt att göra det skalbart.

Hur man får tillgång till API:et

Auktorisering av API:et är endast tillgänglig för kunder på vissa högsta-tier planer. Nå ut till din kund success manager om du är intresserad av att antingen uppgradera eller initiera auktoriseringsprocessen.

Autentiserar med API:et

Autentisering för API:et uppnås genom användning av en JWT-bärarsymbol som ska tillhandahållas i Autentiseringshuvudet för varje begäran till API:et. Tokens är tidsbegränsade till en timme varefter ett nytt tecken måste erhållas.

För att få en token behöver du först en klient id och hemlighet som kommer att tillhandahållas av din kund framgång chef. När du har dessa uppgifter måste du begära token från vår autentiseringsserver som beskrivs nedan.

En exempelbegäran som kan göras med curl visas nedan:

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 från begäran kommer att ha följande struktur:

{
"access_token": "<token att använda i api-förfrågningar>",
"expires_in": 3600,
"refresh_expires_in": 0,
"token_type": "Bearer",
"not-before-policy": 0,
"scope": "email profile"
}

För att korrekt autentisera mot API:et måste du använda värdet på access_token i ovanstående svar som en bärarsymbol i dina förfrågningar till API:et. Detta innebär att behörighetshuvudet för alla förfrågningar ska ha värdet i form av ”Bearer: <token>”. Om du inte har angett en giltig token till API:et kommer ett 401-svar att returneras.

Glossary

Vanliga förfrågningar - Hur man vägleder

• Hur man listar deltagare i ett spel
• Vem är en ”deltagare”? 
• Hitta spelet
• Vad är skillnaden mellan deltagarId och användarId? 
• Hur får man tag på deltagarens e-postadress
• Hur man listar deltagare som fick minst 80% frågor rätt
• Vad händer om 404 returneras? 
• Matchande svar med deltagare 
• Vad betyder ”rätt svar”?
• Förhållandet mellan utslagen tid och korrekt svar

Hur man listar deltagare i ett spel

Vem är en ”deltagare”? 

Följande steg beskriver hur man listar alla spelare som gått in i spelet. 

Observera att “gå med” inte är samma sak som “aktivt spela”. Det är möjligt att gå med i spelet och inte svara på några frågor på grund av anslutningsproblem eller inte vara uppmärksam. Sådana deltagare kommer fortfarande att inkluderas i resultaten. 

Hitta spelet 

åberopa FÅ /v1/organisationer/{organisationId}/games? imit={limit}&startedSince={date} för att lista alla spel som spelas i din organisation inom en given tidsram. Lägg till markör frågeparameter om en annan sida av resultat är tillgänglig och behövs.

Ett exempel på utdata innehåller en lista över spelsessioner:

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

Hitta sessionen i resultaten och kom ihåg att det är spelSessionId. 

Lista deltagare i spelet 

åberopa FÅ /v1/organisationer/{organisationId}/games/{gameSessionId}/deltagare för att lista alla deltagare som gick med i spelet.

Exempel på resultat: 

[

{

"participantId": 1234,

"smeknamn": "Johnny",

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

},

{

"participantId": 4321,

"nickname": "Robert",

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

}

]

Vad är skillnaden mellan deltagareId och userId? 

• deltagareId är ett heltal och är alltid närvarande oavsett spelalternativ.
• deltagareId identifierar endast given spelare inom denna spelsession. Samma deltagareId i en annan spelsession kan och brukar hänvisa till en annan person. 
• userId ingår endast i spel med Player Identifier alternativet aktiverat. Det är då spelarna ombeds att ge sina autentiseringsuppgifter såsom e-post utöver smeknamnet. Eller när de är inbjudna till spelet med hjälp av sina e-postmeddelanden.
• userId gör det möjligt att spåra samma person över flera spelsessioner.

Hur får man tag på deltagarens e-postadress 

åkalla FÅ /v1/organisations/{organisationId}/users/{userId} Det returnerade objektet kommer att innehålla e-post egenskap. 

Hur man listar deltagare som fick minst 80% frågor rätt 

Hitta spelet

Se avsnittet om att hitta spelet. 

Hitta information om kahoot som spelades. Den har två delar: 

1. id - UUID refererar till kahoot som spelades

2. version - kahoot kan ha redigerats av skaparen efter att spelet ägde rum. Varje gång som händer det får versionen egenskapen ökat. Detta säkerställer att svaren hänvisar till korrekta uppgifter. 

{

// andra förmåner

"kahootIdentifier": {

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

"version": 5

},

}

Get participants

Se avsnittet om listning av deltagarna.

Hämta kahoot data 

åkalla GET /v1/organisations/{organisationId}/kahoots/{kahootId}/versions/{version} för att få kahoten med frågeparametrar baserade på kahootIdentifier. d och kahootIdentifier.version egenskaper. 

Resultatet kommer att innehålla alla frågor (block) som ingår av kahoot tillsammans med de svarsalternativ som var tillgängliga för deltagarna om tillämpligt. Frågor och svarsalternativ kommer senare att refereras till i svarsdokumenten. 

Exempel på frågor: 

{

"kahootIdentifier": {

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

"version": 5

},

"title": "Kahoot title",

"description": "Den här kahoot handlar om ...",

"questions": [

{

"contentType": "CONTENT"

"blockIndex": 0

"title": "Det här är företagets presentation"

"description": "Some slide contents"

},

{

"contentType": "SINGLE_SELECT_QUIZ"

"blockIndex": 1

"question": "Vem är vår största kund?" 

 "val": [

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

{"answerText": "Skynet", "korrekt": sant}

]

},

]

}

Få alla svar 

åberopa GET /v1/organisations/{organisationId}/games/{gameSessionId}/blocks/{blockIndex}/answers med gameSessi onId som erhållits när du letar efter spelet (se avsnittet om spelet) och blockIndex som är index för frågan i kahooten. Man måste iterera över alla block (frågor) som spelades, exklusive de som inte var frågor alls (innehåll aka. rutschkanor). 

Följande exempel visar ett svar på det andra blocket av kahoot som var en enda val frågesport, där deltagaren identifierade sig med parti cipantId=1234 (smeknamn “Johnny” som i listande deltagarexempel) och valde det andra valet som råkade vara korrekt. Vi kan också se att deltagaren med smeknamnet “Robert” inte lyckades svara på frågan inom tidsfristen.

{

"blockIndexInKahoot": 1

"answers": [

{

"participantId": 1234,

"answerStatus": "RECEIVED",

"answer": {

"type": "SINGLE_SELECT_QUIZ",

"choice": 1,

"correct": true,

"points": 900

}

},

{

"participantId": 4321,

"answerStatus": "TIMEOUT"

},

]

}

För att veta vad som var valet och vad som var deltagarens smeknamn måste man hänvisa till relaterad kahoot data och deltagarens data som nämns i tidigare avsnitt. 

Vad händer om 404 returneras? 

Svaren på ett visst block kan saknas i följande fall: 

1. Givet fråga (block) är av typen CONTENT. "Svar" dem är inte väldefinierad. 
2. Spelet spelades som en uppgift och ingen av deltagarna nådde den frågan 3. 
3. Det fanns ett nätverk problem under spelet och svaret sparades inte (sällsynt fall, men möjligt att hända).

I vilket fall som helst måste kunderna vara beredda på att svarsuppgifterna saknas där. 

Matchande svar med deltagare 

Svaren innehåller endast länkar till deltagarna vars uppgifter finns i separat slutpunktens svarslast (se avsnittet "Lista deltagare i spelet"). Den länken är deltagareId egenskap finns i båda nyttolasterna. 

Vad betyder ”rätt svar”? 

I fallet med vissa frågetyper finns det ett gråområde mellan ”felaktig” och ”korrekt” svarsstatus.

Multiple-select frågesport frågor 

KORRECT - deltagaren valde alla korrekta val och ingen av de fel

PARTIALLY_CORRECT - deltagaren valde minst ett av de rätta valen och inget av de fel WRONG - deltagaren valde minst ett av fel val

Reglage frågor 

CORRECT - deltagaren valde rätt värde på reglaget

ALMOST_CORRECT - deltagaren valde ett värde som inte var exakt, men inom den tolerans som kahoot skaparen FEL - det valda värdet låg utanför toleransområdet

Alla andra frågor 

För alla andra frågor som kan kan ha rätt eller fel svar finns det bara två alternativ: RÄTT och FEL.

Relation mellan tidsinställda och korrekta svar 

ParticipantAnswer objekt med status lika med TIMEOUT kommer inte att ha svar fastighet, så de är varken "korrekta" eller "fel".  Det är upp till användaren att bestämma hur de ska behandlas. De tilldelas alltid noll poäng under spelet.

Presentation av API-data.

Det finns många sätt att presentera utvunna API-data. Här är ett exempel på Kahoot! data visualiserade i Power BI.

💡 Var det här till hjälp? Prenumerera på vår Youtube-kanal för fler tips och Kahoot! handledning!