Przewodnik po Kahoot! raporty API

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

• 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 korzystać z interfejsu 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. 

Interfejs API Kahoot udostępnia informacje dotyczące gry, użytkowników, uczestników, organizacji oraz quizów Kahoot utworzonych przez daną organizację. Czasami nasze raporty na platformie mogą zrobić tylko tyle. Dla klientów, którzy często korzystają z produktu lub organizują wydarzenia z dużą liczbą uczestników i chcą śledzić ich aktywność, interfejs API stanowi doskonały sposób na realizację tego zadania w sposób skalowalny.

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 ramach API odbywa się za pomocą tokenu JWT typu „bearer”, który należy podać w nagłówku „Authentication” każdego żądania kierowanego do API. Tokeny są ważne przez godzinę; po upływie tego czasu należy uzyskać nowy token.

Aby uzyskać token, musisz najpierw otrzymać identyfikator klienta (client id) oraz klucz tajny (secret), które dostarczy Ci menedżer ds. obsługi klienta. Po uzyskaniu tych danych uwierzytelniających należy zwrócić się do naszego serwera uwierzytelniającego o wydanie tokenu zgodnie z poniższym opisem.

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 do użycia w żądaniach api>",
"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

Wspólne prośby - poradnik

• Jak sporządzić listę uczestników gry
• Kto jest "uczestnikiem"? 
• Znajdź grę
• Jaka jest różnica między participantId i 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 limitem czasu a poprawną odpowiedzią

Jak sporządzić listę uczestników gry

Kto jest "uczestnikiem"? 

Poniższe kroki opisują, jak wyświetlić listę wszystkich graczy, którzy dołączyli do gry. 

Należy pamiętać, że „dołączenie” to nie to samo, co „aktywne granie”. 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ładowy wynik będzie zawierał listę sesji gry:

{
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,

"nickname": "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 grze Kahoot wraz z opcjami odpowiedzi, które były dostępne dla uczestników, o ile takie istniały. 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": "Kahoot title",

"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 przedstawia odpowiedź na drugi blok quizu Kahoot, który był quizem typu „jedna poprawna odpowiedź”, w którym uczestnik o identyfikatorze participantId=1234 (pseudonim „Johnny”, jak w przykładzie listy uczestników) wybrał drugą opcję, która okazała się prawidłowa. 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 z możliwością wyboru wielu odpowiedzi 

POPRAWNIE – uczestnik wybrał wszystkie poprawne odpowiedzi i żadnej z błędnych 

CZĘŚCIOWO_POPRAWNE - uczestnik wybrał co najmniej jedną poprawną odpowiedź i żadnej błędnej BŁĘDNIE - uczestnik wybrał co najmniej jedną z błędnych odpowiedzi 

Pytania z suwakiem 

POPRAWNIE – uczestnik wybrał prawidłową wartość na suwaku 

NIEMAL_POPRAWNE - uczestnik wybrał wartość, która nie była dokładna, ale mieściła się w zakresie tolerancji ustalonym przez twórcę Kahoot BŁĄD - wybrana wartość wykraczała poza zakres tolerancji

Wszelkie inne pytania 

W przypadku wszystkich pozostałych pytań, które mogą mieć odpowiedzi prawidłowe lub błędne, dostępne są tylko dwie opcje: POPRAWNE oraz BŁĘDNE.

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.

Prezentacja danych z interfejsu API

Istnieje wiele sposobów prezentacji wyodrębnionych danych API. Oto przykład Kahoot! dane wizualizowane w Power BI.

💡 Czy to było pomocne? Subskrybuj nasz kanał Youtube, aby uzyskać więcej wskazówek i Kahoot! samouczki!