Kontaktiere uns
Blog
Bibliothek
Zertifizierung
Shop
  1. Kahoot! Hilfe- und Ressourcen-Center
  2. Spielen und Berichte
  3. Berichte

Leitfaden für Kahoot! Berichte API

Aktualisiert

Du fragst dich, wie du Kahoot! nutzen kannst? Berichte API? Hier erfährst du alles, was du wissen musst, um loszulegen.

Verknüpfungen:

Über die Kahoot API 

Die Kahoot API ist eine REST-API, die der OpenAPI folgt. Du kannst unsere gesamte API-Dokumentation einschließlich der Details zu den Ressourcen und Endpunkten unter https://results.kahoot.com/swagger/einsehen. 

Um die Kahoot API aufrufen zu können, benötigt dein Unternehmen einen autorisierten Zugang. Die API ist am besten für Kunden geeignet, die entweder ein Datenteam oder Entwickler haben, die mit APIs vertraut sind. Mit dieser API kann dein Unternehmen auf alle unten aufgeführten Daten innerhalb der letzten 90 Tage nach Spielende zugreifen. Wir versehen unsere Daten mit einem Zeitstempel und unterstützen Start- und Enddaten für den Zeitpunkt, an dem der Kunde die Daten aus unserem System abruft. 

Die Kahoot-API liefert Informationen über das Spiel, die Nutzer/innen, die Teilnehmer/innen, die Organisationen und die von der Organisation erstellten Kahoots. Manchmal kann unsere Berichterstattung auf der Plattform nur so viel bewirken. Für Kunden, die das Produkt häufig oder mit einer hohen Anzahl von Teilnehmern nutzen und deren Aktivitäten verfolgen wollen, ist die API eine großartige Möglichkeit, dies skalierbar zu tun.

Wie man auf die API zugreift

Die Autorisierung der API ist nur für Kunden mit bestimmten High-Tier-Tarifen verfügbar. Wende dich an deinen Kundenbetreuer, wenn du an einem Upgrade oder der Einleitung des Autorisierungsprozesses interessiert bist.

Authentifizierung mit der API

Die Authentifizierung für die API wird durch die Verwendung eines JWT-Tokens erreicht, das im Authentifizierungs-Header jeder Anfrage an die API angegeben werden sollte. Token sind auf eine Stunde begrenzt, danach muss ein neuer Token erworben werden.

Um ein Token zu erhalten, brauchst du zunächst eine Kundennummer und ein Geheimnis, die du von deinem Kundenbetreuer erhältst. Sobald du diese Anmeldedaten hast, musst du das Token von unserem Authentifizierungsserver anfordern, wie unten beschrieben.

URL

https://access-2.kahoot.com/auth/realms/kahoot-api/protocol/openid-connect/token

Http-Methode

PUT

Autorisierungs-Kopfzeile

Du solltest eine grundlegende Autorisierung mit den von kahoot bereitgestellten Anmeldedaten vornehmen.

Inhalt-Typ-Kopfzeile

application/x-www-form-urlencoded

Inhalt der Anfrage

grant_type=client_credentials

 

Ein Beispiel für eine Anfrage, die mit curl gestellt werden kann, ist unten dargestellt:

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

 

Die Antwort auf die Anfrage hat die folgende Struktur:

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

 

Um dich ordnungsgemäß bei der API zu authentifizieren, musst du den Wert des access_token in der obigen Antwort als Inhaber-Token in deinen Anfragen an die API verwenden. Das bedeutet, dass der Authorization-Header aller Anfragen den Wert in der Form "Bearer" enthalten sollte: <token>". Wenn du kein gültiges Token an die API übermittelt hast, wird eine 401-Antwort zurückgegeben.

Glossar

Begriff

Beschreibung

Live-Spiel

Wenn ein Kahoot in Person gespielt wird.

Herausforderung

Wenn ein Kahoot asynchron gespielt wird.

Punkte

Ganzzahliger Wert. Die Anzahl der Punkte, die der Spieler für diese Frage erhalten hat.

antwortet

Eine Reihe von eingereichten Antworten auf eine Frage.

empfangen, Zeitüberschreitung

Die Antwort auf die Frage.

Timeout

Wenn ein Nutzer keine Antwort auf eine Frage gegeben hat.

Block

Bestimmte Fragetypen werden immer als "Block" bezeichnet, z. B. der Fragetyp Wahr oder Falsch heißt TrueFalseBlock und der Fragetyp Brainstorming wird als BrainstormingBlock bezeichnet.

kahoot

Das eigentliche Kahoot. Das ist etwas anderes als ein Spiel oder eine Spielsitzung (wie wir es nennen, wenn das Kahoot tatsächlich gespielt wird).

Spiel

Wenn das Kahoot gespielt wird.

Spielsitzung

Eine einzigartige Spielinstanz.

Gastgeber

Der Benutzer, der das Spiel gestartet hat.

Kahoot-Version

Wenn Kahoots geändert werden, speichern wir verschiedene Versionen des Kahoots. Es können verschiedene Versionen eines Kahoot gespielt werden und somit auch verschiedene Antworten gespeichert werden. Die Version des kahoot, bei der 0 angegeben ist, ist nicht versioniert.

Kurs

Einige Spiele sind an Kurse gebunden. Wenn das der Fall ist, wird eine Kurs-ID angegeben.

Blockindex - Kahoot

Index, bei dem das Spiel ursprünglich im zugehörigen Kahoot erschienen ist (0-basiert).

Blockindex - Spiel

Index, bei dem das Spiel während der Spielsitzung erschien (0-basiert).

Kann sich von blockIndexInKahoot unterscheiden, wenn eine zufällige Reihenfolge der Fragen verwendet wurde.

Fragen

Liste der Fragen im Kahoot.

Brainstorming (Fragetyp)

Offene Fragen, bei denen die Teilnehmer Ideen einreichen und abstimmen.

Drop Pin (Fragetyp)

Frage ohne Punkte, bei der die Teilnehmenden Stecknadeln auf ein Bild fallen lassen können.

Umfrage (Fragetyp)

Frage ohne Punkte, bei der die Spieler/innen bis zu 6 Optionen in einer Frage wählen können.

Multiselect-Quiz (Fragetyp)

Gib den Spielern bei einer Frage mehrere Antworten zur Auswahl.

Open Ended (Fragetyp)

Frage, die die Spieler/innen in einer langen Textantwort beantworten sollen.

Puzzle (Fragetyp)

Frage, bei der die Spieler die Antworten in die richtige Reihenfolge bringen müssen.

Schieberegler (Fragetyp)

Die Teilnehmer erraten die richtige Zahl in einem Bereich.

Richtig Falsch (Fragetyp)

Die Teilnehmer entscheiden, ob eine Aussage wahr oder falsch ist.

Typ Antwort (Fragetyp)

Die Teilnehmer antworten mit einem kurzen Text.

Wortwolke (Fragetyp)

Frage, die kurze Freiform-Umfragefragen sammelt.

Allgemeine Anfragen - Leitfaden

Wie man die Teilnehmer eines Spiels auflistet

Wer ist ein "Teilnehmer"? 

Die folgenden Schritte beschreiben, wie du alle Spieler auflistest, die am Spiel teilgenommen haben. 

Bitte beachte, dass "beitreten" nicht dasselbe ist wie "aktiv spielen". Es ist möglich, dass du am Spiel teilnimmst und keine Fragen beantwortest, weil du Verbindungsprobleme hast oder nicht aufpasst. Diese Teilnehmerinnen und Teilnehmer werden weiterhin in den Ergebnissen berücksichtigt. 

Finde das Spiel 

Rufe GET /v1/organisations/{organisationId}/games?limit={limit}&startedSince={date} auf, um alle Spiele aufzulisten, die in deiner Organisation in einem bestimmten Zeitraum gespielt wurden. Füge den Abfrageparameter cursor hinzu, falls eine weitere Ergebnisseite verfügbar ist und benötigt wird.

Eine Beispielausgabe enthält eine Liste der Spielsitzungen:

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

Finde die Sitzung in den Ergebnissen und merke sie dir: gameSessionId. 

Liste der Teilnehmer des Spiels 

Rufe GET /v1/organisations/{organisationId}/games/{gameSessionId}/participants auf, um alle Teilnehmer aufzulisten, die dem Spiel beigetreten sind.

Beispielergebnis: 

[

{

"participantId": 1234,

"nickname": "Johnny",

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

},

{

"participantId": 4321,

"nickname": "Robert",

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

}

]

Was ist der Unterschied zwischen participantId und userId? 

  • participantId ist eine ganze Zahl und ist unabhängig von den Spieloptionen immer vorhanden.
  • participantId identifiziert einen bestimmten Spieler nur innerhalb dieser Spielsitzung. Dieselbe participantId in einer anderen Spielsitzung kann sich auf eine andere Person beziehen und tut dies normalerweise auch. 
  • userId ist nur in Spielen enthalten, in denen die Option "Spieleridentifikation" aktiviert ist. Dann werden die Spielerinnen und Spieler gebeten, neben dem Spitznamen auch ihre Anmeldedaten wie z.B. ihre E-Mail-Adresse anzugeben. Oder wenn sie über ihre E-Mails zum Spiel eingeladen werden.
  • userId macht es möglich, dieselbe Person über mehrere Spielsitzungen hinweg zu verfolgen.

So bekommst du die E-Mail-Adresse des Teilnehmers 

Rufe GET /v1/organisations/{organisationId}/users/{userId} auf. Das zurückgegebene Objekt enthält email property. 

Wie man Teilnehmer auflistet, die mindestens 80% der Fragen richtig beantwortet haben 

Finde das Spiel

Siehe den Abschnitt über das Finden des Spiels. 

Finde die Informationen über das Kahoot, das gespielt wurde. Sie besteht aus zwei Teilen: 

  1. id - UUID mit Verweis auf das Kahoot, das gespielt wurde
  1. Version - das Kahoot könnte vom Ersteller bearbeitet worden sein, nachdem das Spiel stattgefunden hat. Jedes Mal, wenn das passiert, wird die Eigenschaft "Version" erhöht. So wird sichergestellt, dass sich die Antworten auf die richtigen Daten beziehen.  
{

// andere Requisiten

"kahootIdentifier": {

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

"version": 5

},

}

Teilnehmer bekommen

Siehe den Abschnitt zur Auflistung der Teilnehmer.

Kahoot-Daten erhalten 

Rufe GET /v1/organisations/{organisationId}/kahoots/{kahootId}/versions/{version} auf, um das Kahoot mit Abfrageparametern basierend auf den Eigenschaften kahootIdentifier.id und kahootIdentifier.version zu erhalten. 

Das Ergebnis enthält alle Fragen (Blöcke) aus dem Kahoot sowie die Antwortmöglichkeiten, die den Teilnehmern zur Verfügung standen, falls zutreffend. Auf die Fragen und Antwortmöglichkeiten wird später in den Antwortdokumenten verwiesen. 

Beispielfragen: 

{

"kahootIdentifier": {

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

"version": 5

},

"title": "Kahoot title",

"description": "In diesem Kahoot geht es um ...",

"questions": [

{

"contentType": "CONTENT"

"blockIndex": 0

"title": "Dies ist die Unternehmenspräsentation"

"description": "Einige Folieninhalte"

},

{

"contentType": "SINGLE_SELECT_QUIZ"

"blockIndex": 1

"question": "Wer ist unser größter Kunde?" 

"choices": [

{"answerText": "Very Big Corp. of America", "richtig": falsch},

{"answerText": "Skynet", "richtig": wahr}

]

},

]

}

Alle Antworten erhalten 

Rufe GET /v1/organisations/{organisationId}/games/{gameSessionId}/blocks/{blockIndex}/answers auf, indem du gameSessi onId verwendest, die du bei der Suche nach dem Spiel erhalten hast (siehe Abschnitt "Spiel finden"), und blockIndex als Index der Frage im Kahoot. Man muss über alle Blöcke (Fragen) iterieren, die gespielt wurden, ohne die Blöcke, die gar keine Fragen waren (Inhalt aka. Folien). 

Das folgende Beispiel zeigt eine Antwort auf den zweiten Block des Kahoot, bei dem es sich um ein Single-Select-Quiz handelte. Der Teilnehmer identifizierte sich mit parti cipantId=1234 (Spitzname "Johnny" wie in der Teilnehmerliste Beispiel) und wählte die zweite Auswahlmöglichkeit, die zufällig richtig war. Wir können auch sehen, dass der Teilnehmer mit dem Spitznamen "Robert" es nicht geschafft hat, die Frage innerhalb des Zeitlimits zu beantworten.

{

"blockIndexInKahoot": 1

"answers": [

{

"participantId": 1234,

"answerStatus": "RECEIVED",

"answer": {

"type": "SINGLE_SELECT_QUIZ",

"choice": 1,

"correct": true,

"points": 900

}

},

{

"participantId": 4321,

"answerStatus": "TIMEOUT"

},

]

}

Um herauszufinden, wie die Wahl ausfiel und wie der Spitzname des Teilnehmers lautete, muss man sich auf die entsprechenden kahoot Daten und die Teilnehmerdaten beziehen, die in den vorherigen Abschnitten erwähnt wurden. 

Was ist, wenn 404 zurückgegeben wird? 

In den folgenden Fällen können die Antworten für einen bestimmten Block fehlen: 

  1. Die gegebene Frage (Block) ist vom Typ CONTENT. Sie zu "beantworten" ist nicht klar definiert. 
  2. Das Spiel wurde als Aufgabe gespielt und keiner der Teilnehmer erreichte diese Frage 3. 
  3. Während des Spiels gab es ein Netzwerkproblem und die Antwort wurde nicht gespeichert (seltener Fall, kann aber vorkommen).

In jedem Fall müssen die Kunden darauf vorbereitet sein, dass die Antwortdaten dort fehlen könnten. 

Antworten mit Teilnehmern abgleichen 

Die Antworten enthalten nur die Links zu den Teilnehmern, deren Details in der Antwort-Payload des separaten Endpunkts enthalten sind (siehe Abschnitt "Liste der Teilnehmer des Spiels"). Dieser Link ist participantId Eigenschaft, die in beiden Payloads vorhanden ist. 

Was bedeutet "richtige Antwort"? 

Bei einigen Fragetypen gibt es eine Grauzone zwischen "falscher" und "richtiger" Antwort.

Quizfragen mit Mehrfachauswahl 

RICHTIG - der Teilnehmer hat alle richtigen Möglichkeiten ausgewählt und keine der falschen

PARTIALLY_CORRECT - der Teilnehmer hat mindestens eine der richtigen und keine der falschen Möglichkeiten ausgewählt WRONG - der Teilnehmer hat mindestens eine der falschen Möglichkeiten ausgewählt

Fragen zum Schieberegler 

RICHTIG - der Teilnehmer hat den richtigen Wert auf dem Schieberegler ausgewählt

ALMOST_CORRECT - der Teilnehmer hat einen Wert ausgewählt, der nicht genau, aber innerhalb der vom Kahoot-Ersteller festgelegten Toleranz lag WRONG - der ausgewählte Wert lag außerhalb des Toleranzbereichs

Alle anderen Fragen 

Bei allen anderen Fragen, die richtig oder falsch beantwortet werden können, gibt es nur zwei Auswahlmöglichkeiten: RICHTIG und FALSCH.

Verhältnis zwischen Zeitüberschreitung und richtiger Antwort 

ParticipantAnswer Objekte mit status gleich TIMEOUT haben keine answer Eigenschaft, also sind sie weder "richtig" noch "falsch".  Es liegt an der Nutzerin/dem Nutzer zu entscheiden, wie sie/er damit umgehen will. Während des Spiels werden ihnen immer null Punkte zugewiesen.

Verwandte Beiträge

Berichte

Verwandte Beiträge

Berichte

0 Kommentare

Bitte melden Sie sich an, um einen Kommentar zu hinterlassen.