Przewodnik po Kahoot! raporty API

Zastanawiasz się, jak używać Kahoot! raporty API? Oto wszystko, co musisz wiedzieć, aby zacząć.

Skróty:

• O API Kahoot
• Jak uzyskać dostęp do API
• Uwierzytelnianie za pomocą API
• Słowniczek
• Wspólne prośby - poradnik

O API Kahoot 

API Kahoot to interfejs REST API zgodny z OpenAPI. Całą dokumentację API, w tym szczegóły dotyczące zasobów i punktów końcowych, możesz przejrzeć na stronie https://results.kahoot.com/swagger/. 

Aby móc wykonywać połączenia z API Kahoot, Twoja firma będzie potrzebowała autoryzowanego dostępu. Interfejs API jest najlepszym rozwiązaniem dla klientów, którzy mają zespół zajmujący się danymi lub programistów zaznajomionych z interfejsami API. Dzięki temu API Twoja firma będzie mogła uzyskać dostęp do wszystkich danych wymienionych poniżej w ciągu ostatnich 90 dni od zakończenia gry. Oznaczamy nasze dane znacznikami czasowymi i obsługujemy daty rozpoczęcia i zakończenia pobierania danych z naszego systemu przez klienta. 

API Kahoot podaje informacje dotyczące gry, użytkowników, uczestników, organizacji i kahootów stworzonych przez organizację. Czasami nasze raporty na platformie mogą zrobić tylko tyle. Dla klientów, którzy korzystają z produktu często lub z dużą liczbą uczestników i chcą śledzić ich aktywność, interfejs API jest doskonałym sposobem na skalowalność.

Jak uzyskać dostęp do API

Autoryzacja interfejsu API jest dostępna tylko dla klientów korzystających z niektórych planów najwyższego poziomu. Skontaktuj się z menedżerem ds. obsługi klienta, jeśli jesteś zainteresowany aktualizacją lub rozpoczęciem procesu autoryzacji.

Uwierzytelnianie za pomocą API

Uwierzytelnianie w interfejsie API odbywa się za pomocą tokena JWT, który należy podać w nagłówku Uwierzytelnianie każdego żądania do interfejsu API. Żetony są ograniczone czasowo do godziny, po której należy zdobyć nowy żeton.

Aby otrzymać token, będziesz potrzebował identyfikatora i sekretu klienta, które dostarczy ci kierownik ds. sukcesu klienta. Po uzyskaniu tych danych musisz poprosić o token z naszego serwera uwierzytelniającego w sposób opisany poniżej.

URL	https://access-2.kahoot.com/auth/realms/kahoot-api/protocol/openid-connect/token
Metoda Http	PUT
Nagłówek autoryzacji	Należy zapewnić podstawowy nagłówek autoryzacji, używając poświadczeń dostarczonych przez kahoot.
Nagłówek Content-Type	application/x-www-form-urlencoded
Treść wniosku	grant_type=client_credentials

 

Poniżej przedstawiono przykładowe żądanie, które można wykonać za pomocą 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

 

Odpowiedź na żądanie będzie miała następującą 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"
}

 

Aby prawidłowo uwierzytelnić się w API, musisz użyć wartości access_token z powyższej odpowiedzi jako tokena okaziciela w swoich żądaniach do API. Oznacza to, że nagłówek Authorization wszystkich żądań powinien mieć wartość w postaci "Bearer: <token>". Jeśli nie podałeś poprawnie poprawnego tokena do interfejsu API, zostanie zwrócona odpowiedź 401.

Słowniczek

Termin	Opis
Gra na żywo	Kiedy kahoot jest rozgrywany osobiście.
Wyzwanie	Kiedy kahoot jest odtwarzany asynchronicznie.
punkty	Wartość całkowita. Liczba punktów, które gracz otrzymał za to pytanie.
odpowiedzi	Zestaw przesłanych odpowiedzi na pytanie.
odebrane, timeout	Odpowiedź na pytanie.
timeout	Gdy użytkownik nie udzielił odpowiedzi na pytanie.
Blok	Określone typy pytań są zawsze określane jako "blok", na przykład pytania typu Prawda czy Fałsz są określane jako TrueFalseBlock, a pytania typu Burza Mózgów jako BrainstormBlock.
kahoot	Prawdziwy kahoot. Jest to coś innego niż gra lub sesja gry (co nazywamy, gdy kahoot jest rzeczywiście rozgrywany).
gry Kahoot!.	Kiedy zostanie rozegrany kahoot.
sesja gier	Wyjątkowa instancja gry.
prezentuj	Użytkownik, który uruchomił grę.
wersja kahoot	Jeśli kahoot jest modyfikowany, przechowujemy różne wersje tego kahoota. Można grać w różne wersje kahoota i zapisywać różne odpowiedzi. Wersja kahoot, w której wskazano 0, nie jest wersjonowana.
kursu	Niektóre gry są powiązane z kursami - w takim przypadku podany zostanie identyfikator kursu.
Indeks bloku - Kahoot	Indeks, na którym gra pojawiła się w powiązanym kahoocie (oparty na 0).
Indeks bloków - Gra	Indeks, w którym gra pojawiła się podczas sesji gry (w oparciu o 0). Może być inny niż blockIndexInKahoot, jeśli zastosowano losową kolejność pytań.
liczba pytań	Lista pytań w kahoot.
Burza mózgów (typ pytania)	Pytanie otwarte, w którym uczestnicy zgłaszają pomysły i głosują.
Kołek rozporowy (typ pytania)	Pytanie bez punktów, w którym uczestnicy mogą upuszczać pinezki na obrazek.
Poll (typ pytania)	Pytanie bez punktów, w którym gracze wybierają do 6 opcji w pytaniu.
Quiz wielokrotnego wyboru (typ pytania)	Daj graczom kilka odpowiedzi do wyboru w pytaniu.
Otwarte (typ pytania)	Pytanie, na które gracze mają odpowiedzieć w formie długiej odpowiedzi tekstowej.
Puzzle (typ pytania)	Pytanie, w którym gracze układają odpowiedzi w odpowiedniej kolejności.
Suwak (typ pytania)	Uczestnicy odgadują prawidłową liczbę w danym przedziale.
Prawda Fałsz (typ pytania)	Uczestnicy decydują, czy dane stwierdzenie jest prawdziwe czy fałszywe.
Typ Odpowiedź (typ pytania)	Uczestnicy odpowiadają za pomocą krótkiego tekstu.
Chmura słów (typ pytania)	Pytanie, które gromadzi krótkie, dowolne pytania ankietowe.

Wspólne prośby - poradnik

• Jak sporządzić listę uczestników gry
• Kto jest "uczestnikiem"? 
• Znajdź grę
• Jaka jest różnica między participantId a userId? 
• Jak zdobyć adres e-mail uczestnika
• Jak sporządzić listę uczestników, którzy uzyskali co najmniej 80% poprawnych odpowiedzi na pytania
• Co się stanie, jeśli zostanie zwrócone 404? 
• Dopasowywanie odpowiedzi do uczestników 
• Co oznacza "poprawna odpowiedź"?
• Zależność między czasem oczekiwania na odpowiedź a poprawnością odpowiedzi

Jak sporządzić listę uczestników gry

Kto jest "uczestnikiem"? 

W poniższych krokach opisano, jak zrobić listę wszystkich graczy, którzy weszli do gry. 

Pamiętaj, że "dołączenie" to nie to samo, co "aktywna gra". Można dołączyć do gry i nie odpowiadać na żadne pytania z powodu problemów z połączeniem lub braku uwagi. Tacy uczestnicy nadal będą uwzględniani w wynikach. 

Znajdź grę 

Wywołaj GET /v1/organisations/{organisationId}/games?limit={limit}&beganSince={date} , aby wyświetlić listę wszystkich gier rozegranych w Twojej organizacji w określonym czasie. Dodaj parametr zapytania cursor na wypadek, gdyby była dostępna i potrzebna kolejna strona wyników.

Przykładowe wyjście będzie zawierać listę sesji gier:

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

Znajdź sesję w wynikach i zapamiętaj jej nazwę gameSessionId. 

Lista uczestników gry 

Wywołaj GET /v1/organisations/{organisationId}/games/{gameSessionId}/participants , aby wyświetlić listę wszystkich uczestników, którzy dołączyli do gry.

Przykładowy wynik: 

[

{

"participantId": 1234,

"nick": "Johnny",

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

},

{

"participantId": 4321,

"nick": "Robert",

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

}

]

Jaka jest różnica między participantId a userId? 

• participantId jest liczbą całkowitą i jest zawsze obecny, niezależnie od opcji gry.
• participantId identyfikuje danego gracza tylko w ramach tej sesji gry. Ten sam participantId w innej sesji gry może i zazwyczaj odnosi się do innej osoby. 
• userId jest uwzględniany tylko w grach z włączoną opcją identyfikatora gracza. To właśnie wtedy gracze są proszeni o podanie swoich danych, takich jak e-mail, a także pseudonim. Albo gdy są zapraszani do gry za pomocą swoich e-maili.
• userId umożliwia śledzenie tej samej osoby podczas wielu sesji gry.

Jak zdobyć adres e-mail uczestnika 

Wywołaj GET /v1/organisations/{organisationId}/users/{userId} Zwrócony obiekt będzie zawierał email właściwość. 

Jak sporządzić listę uczestników, którzy uzyskali co najmniej 80% poprawnych odpowiedzi na pytania 

Znajdź grę

Zobacz rozdział o poszukiwaniu gry. 

Znajdź informacje o rozegranym meczu kahoot. Składa się z dwóch części: 

1. id - UUID odnoszący się do kahoota, który został odtworzony

2. wersja - kahoot mógł być edytowany przez twórcę po przeprowadzeniu gry. Za każdym razem, gdy tak się stanie, zostanie zwiększona właściwość version. To gwarantuje, że odpowiedzi odnoszą się do prawidłowych danych. 

{

// inne właściwości

"kahootIdentifier": {

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

"version": 5

},

}

Pobierz uczestników

Zobacz rozdział o wymienianiu uczestników.

Pobierz dane z kahoot 

Wywołaj GET /v1/organisations/{organisationId}/kahoots/{kahootId}/versions/{version} , aby uzyskać kahoot z parametrami zapytania opartymi na właściwościach kahootIdentifier.id i kahootIdentifier.version . 

Wynik będzie zawierał wszystkie pytania (bloki) zawarte w kahoocie wraz z odpowiedziami, które były dostępne dla uczestników, jeśli dotyczy. Pytania i wybory odpowiedzi będą później przywoływane przez dokumenty z odpowiedziami. 

Przykładowe pytania: 

{

"kahootIdentifier": {

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

"version": 5

},

"title": "Tytuł Kahoot",

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

"questions": [

{

"contentType": "CONTENT"

"blockIndex": 0

"title": "To jest prezentacja firmy"

"description": "Some slide contents"

},

{

"contentType": "SINGLE_SELECT_QUIZ"

"blockIndex": 1

"question": "Kto jest naszym największym klientem?" 

"choices": [

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

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

]

},

]

}

Uzyskaj wszystkie odpowiedzi 

Wywołaj GET /v1/organisations/{organisationId}/games/{gameSessionId}/blocks/{blockIndex}/answers używając gameSessi onId uzyskanego podczas szukania gry (patrz sekcja Znajdź grę) oraz blockIndex będącego indeksem pytania w kahoot. Trzeba iterować po wszystkich blokach (pytaniach), które zostały rozegrane, wyłączając te, które w ogóle nie były pytaniami (treść aka. slajdów). 

Poniższy przykład pokazuje odpowiedź w drugim bloku kahoota, który był quizem jednokrotnego wyboru, gdzie uczestnik zidentyfikował się z parti cipantId=1234 (nick "Johnny", jak w przykładzie listing participants) i wybrał drugi wybór, który okazał się poprawny. Widzimy też, że uczestnik o pseudonimie "Robert" nie zdążył odpowiedzieć na pytanie w wyznaczonym czasie.

{

"blockIndexInKahoot": 1

"answers": [

{

"participantId": 1234,

"answerStatus": "RECEIVED",

"answer": {

"type": "SINGLE_SELECT_QUIZ",

"choice": 1,

"correct": true,

"points": 900

}

},

{

"participantId": 4321,

"answerStatus": "TIMEOUT"

},

]

}

Aby dowiedzieć się, jaki był wybór i jaki był pseudonim uczestnika, należy odwołać się do powiązanych danych kahoot oraz danych uczestnika wspomnianych w poprzednich częściach. 

Co się stanie, jeśli zostanie zwrócone 404? 

Odpowiedzi dla danego bloku może zabraknąć w następujących przypadkach: 

1. Podane pytanie (blok) jest typu CONTENT. "Odpowiadanie" na nie nie jest dobrze zdefiniowane. 
2. Gra została rozegrana jako zadanie i żaden z uczestników nie dotarł do tego pytania 3. 
3. Podczas rozgrywki wystąpił problem z siecią i odpowiedź nie została zapisana (rzadki przypadek, ale możliwy).

W każdym przypadku klienci muszą być przygotowani na to, że może tam brakować danych do odpowiedzi. 

Dopasowywanie odpowiedzi do uczestników 

Odpowiedzi zawierają tylko linki do uczestników, których dane są zawarte w osobnym pliku odpowiedzi endpointu (patrz sekcja "Lista uczestników gry"). Tym łączem jest participantId właściwość obecna w obu payloadach. 

Co oznacza "poprawna odpowiedź"? 

W przypadku niektórych typów pytań istnieje pewien szary obszar pomiędzy statusem odpowiedzi "niepoprawnej" i "poprawnej".

Pytania quizowe wielokrotnego wyboru 

PRAWDA - uczestnik wybrał wszystkie poprawne wybory i żadnego z niewłaściwych

PARTIALLY_CORRECT - uczestnik wybrał przynajmniej jedną z prawidłowych opcji i żadnej z nieprawidłowych WRONG - uczestnik wybrał przynajmniej jedną z nieprawidłowych opcji

Pytania z suwakiem 

PRAWDA - uczestnik wybrał właściwą wartość na suwaku

ALMOST_CORRECT - uczestnik wybrał wartość, która nie była dokładna, ale mieściła się w granicach tolerancji ustalonej przez twórcę kahoota WRONG - wybrana wartość była poza granicami tolerancji

Wszystkie inne pytania 

Dla wszystkich innych pytań, które mogą mieć dobre lub złe odpowiedzi, są tylko dwie możliwości: PRAWDA oraz ZŁA.

Zależność między czasem oczekiwania na odpowiedź a poprawnością odpowiedzi 

Obiekty ParticipantAnswer z statusem równym TIMEOUT nie będą miały właściwości odpowiedź , więc nie są ani "poprawne", ani "błędne".  Decyzja o tym, jak je traktować, należy do użytkownika. Podczas gry zawsze otrzymują zero punktów.