Guida a Kahoot! rapporti API

Ti stai chiedendo come usare Kahoot! rapporti API? Ecco tutto quello che devi sapere per iniziare.

Accesso rapido:

• Informazioni sull'API di Kahoot
• Come accedere all'API
• Autenticazione con l'API
• Glossario
• Richieste comuni - Guida alle modalità

Informazioni sull'API di Kahoot 

L'API di Kahoot è un'API REST che segue le OpenAPI. Puoi consultare tutta la documentazione delle nostre API, compresi i dettagli delle risorse e degli endpoint, all'indirizzo https://results.kahoot.com/swagger/. 

Per poter effettuare chiamate all'API di Kahoot, la tua azienda dovrà avere un accesso autorizzato. L'API è ideale per i clienti che dispongono di un team di dati o di sviluppatori che hanno familiarità con le API. Con questa API la tua azienda potrà accedere a tutti i dati elencati di seguito negli ultimi 90 giorni dopo la fine del gioco. Noi apponiamo una data di inizio e fine ai nostri dati e supportiamo le date in cui il cliente preleva i dati dal nostro sistema. 

L'API di Kahoot riporta le informazioni relative al gioco, agli utenti, ai partecipanti, alle organizzazioni e ai kahoot creati dall'organizzazione. A volte, i nostri resoconti sulla piattaforma possono fare solo un po' di tutto. Per i clienti che utilizzano il prodotto frequentemente o con un numero elevato di partecipanti e vogliono tracciare la loro attività, l'API è un ottimo modo per farlo in modo scalabile.

Come accedere all'API

L'autorizzazione dell'API è disponibile solo per i clienti con alcuni piani di livello più alto. Rivolgiti al tuo Customer Success Manager se sei interessato ad aggiornare o ad avviare il processo di autorizzazione.

Autenticazione con l'API

L'autenticazione per l'API avviene attraverso l'uso di un token JWT che deve essere fornito nell'intestazione Authentication di ogni richiesta all'API. I gettoni hanno una durata limitata di un'ora, al termine della quale è necessario ottenere un nuovo gettone.

Per ottenere un token dovrai prima ottenere un id e un segreto del cliente che ti verranno forniti dal tuo responsabile del successo del cliente. Una volta ottenute queste credenziali, dovrai richiedere il token al nostro server di autenticazione come descritto di seguito.

Un esempio di richiesta che potrebbe essere fatta con curl è mostrato di seguito:

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

La risposta alla richiesta avrà la seguente struttura:

{
"access_token": "<token da utilizzare nelle richieste api>",
"expires_in": 3600,
"refresh_expires_in": 0,
"token_type": "Bearer",
"not-before-policy": 0,
"scope": "profilo e-mail"
}

Per autenticarti correttamente all'API, devi utilizzare il valore dell'access_token nella risposta precedente come token del portatore nelle tue richieste all'API. Ciò significa che l'intestazione Authorization di tutte le richieste deve avere il valore "Bearer: <token>". Se non hai fornito correttamente un token valido all'API, verrà restituita una risposta 401.

Glossario

Richieste comuni - Guida alle modalità

• Come elencare i partecipanti a una partita
• Chi è un "partecipante"? 
• Trova il gioco
• Qual è la differenza tra participantId e userId? 
• Come ottenere l'indirizzo e-mail del partecipante
• Come elencare i partecipanti che hanno azzeccato almeno l'80% delle domande
• Cosa succede se viene restituito 404? 
• Abbinare le risposte ai partecipanti 
• Cosa significa "risposta corretta"?
• Relazione tra tempo di uscita e risposta corretta

Come elencare i partecipanti a una partita

Chi è un "partecipante"? 

I passi seguenti descrivono come elencare tutti i giocatori che hanno partecipato alla partita. 

Tieni presente che "iscriversi" non equivale a "giocare attivamente". È possibile partecipare al gioco e non rispondere alle domande per problemi di connessione o per mancanza di attenzione. Questi partecipanti saranno comunque inclusi nei risultati. 

Trova il gioco 

Invoca GET /v1/organisations/{organisationId}/games?limit={limit}&startedSince={date} per elencare tutte le partite giocate nella tua organizzazione in un determinato periodo di tempo. Aggiungi il parametro di query cursor nel caso in cui sia disponibile e necessaria un'altra pagina di risultati.

Un esempio di output conterrà un elenco di sessioni di gioco:

{
dati: [
"gameSessionId": "3c28c370-0407-416f-a44f-087715b4ea89", "hostUserId": "70feec9e-1ee3-4e35-8d6b-0fe44d9f2358", "kahootIdentifier": {
 "id": "3c28c370-0407-416f-a44f-087715b4ea89", 
 "version": 5 
},
"startTime": 1667928438123,
}
],
cursore: "abcxyz"
}

Trova la sessione nei risultati e ricorda che è gameSessionId. 

Elenco dei partecipanti al gioco 

Invoca GET /v1/organisations/{organisationId}/games/{gameSessionId}/participants per elencare tutti i partecipanti che si sono uniti al gioco.

Risultato del campione: 

[

{

"participantId": 1234,

"nickname": "Johnny",

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

},

{

"participantId": 4321,

"nickname": "Robert",

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

}

]

Qual è la differenza tra participantId e userId? 

• participantId è un numero intero ed è sempre presente indipendentemente dalle opzioni di gioco.
• participantId identifica un determinato giocatore solo all'interno di questa sessione di gioco. Lo stesso participantId in una sessione di gioco diversa può e di solito si riferisce a una persona diversa. 
• userId è incluso solo nelle partite con l'opzione Identificatore giocatore attivata. A questo punto viene chiesto ai giocatori di fornire le loro credenziali, come l'e-mail, oltre al nickname. Oppure quando vengono invitati al gioco utilizzando la loro e-mail.
• userId permette di rintracciare la stessa persona in più sessioni di gioco.

Come ottenere l'indirizzo e-mail del partecipante 

Invoca GET /v1/organisations/{organisationId}/users/{userId} L'oggetto restituito conterrà la proprietà email . 

Come elencare i partecipanti che hanno azzeccato almeno l'80% delle domande 

Trova il gioco

Vedi la sezione relativa alla ricerca del gioco. 

Trova le informazioni sul kahoot che è stato giocato. Si compone di due parti: 

1. id - UUID che fa riferimento al kahoot riprodotto

2. versione - il kahoot potrebbe essere stato modificato dal creatore dopo lo svolgimento del gioco. Ogni volta che ciò accade, la proprietà version viene incrementata. Questo assicura che le risposte si riferiscano a dati corretti. 

{

// altre proprietà

"kahootIdentifier": {

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

"version": 5

},

}

Ottieni i partecipanti

Vedi la sezione sull'elenco dei partecipanti.

Ottieni i dati di kahoot 

Invoca GET /v1/organisations/{organisationId}/kahoots/{kahootId}/versions/{version} per ottenere il kahoot con i parametri di query basati sulle proprietà kahootIdentifier.id e kahootIdentifier.version . 

Il risultato conterrà tutte le domande (blocchi) contenute nel kahoot insieme alle opzioni di risposta disponibili per i partecipanti, se applicabili. Le domande e le opzioni di risposta saranno successivamente referenziate dai documenti di risposta. 

Domande di esempio: 

{

"kahootIdentifier": {

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

"version": 5

},

"title": "Kahoot title",

"description": "Questo kahoot riguarda ...",

"domande": [

{

"contentType": "CONTENT"

"blockIndex": 0

"title": "Questa è la presentazione aziendale"

"description": "Alcuni contenuti delle diapositive"

},

{

"contentType": "SINGLE_SELECT_QUIZ"

"blockIndex": 1

"question": "Chi è il nostro cliente più importante?". 

 "scelte": [

{"answerText": "Very Big Corp. of America", "corretto": falso},

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

]

},

]

}

Ottieni tutte le risposte 

Invoca GET /v1/organisations/{organisationId}/games/{gameSessionId}/blocks/{blockIndex}/answers utilizzando gameSessi onId ottenuto quando si cerca il gioco (vedi la sezione trovare il gioco) e blockIndex che è l'indice della domanda nel kahoot. Bisogna iterare su tutti i blocchi (domande) che sono stati giocati, escludendo quelli che non erano affatto domande (contenuti). diapositive). 

L'esempio seguente mostra una risposta al secondo blocco del kahoot, che era un quiz a selezione singola, in cui il partecipante si è identificato con parti cipantId=1234 (nickname "Johnny" come nell'esempio di elenco dei partecipanti) e ha selezionato la seconda scelta, che si è rivelata corretta. Possiamo anche notare che il partecipante con il nickname "Robert" non è riuscito a rispondere alla domanda entro il tempo limite.

{

"blockIndexInKahoot": 1

"risposte": [

{

"participantId": 1234,

"answerStatus": "RECEIVED",

"answer": {

"type": "SINGLE_SELECT_QUIZ",

"choice": 1,

"corretto": true,

"punti": 900

}

},

{

"participantId": 4321,

"answerStatus": "TIMEOUT"

},

]

}

Per sapere qual è stata la scelta e qual è il nickname dei partecipanti è necessario fare riferimento ai dati kahoot e ai dati dei partecipanti menzionati nelle sezioni precedenti. 

Cosa succede se viene restituito 404? 

Le risposte per un determinato blocco possono mancare nei seguenti casi: 

1. La domanda data (blocco) è del tipo CONTENT. "Rispondere non è ben definito. 
2. Il gioco è stato svolto come un compito e nessuno dei partecipanti ha raggiunto la domanda 3. 
3. C'è stato un problema di rete durante il gioco e la risposta non è stata salvata (caso raro, ma possibile).

In ogni caso, i clienti devono essere preparati al fatto che i dati di risposta potrebbero mancare. 

Abbinare le risposte ai partecipanti 

Le risposte contengono solo i link ai partecipanti i cui dettagli sono contenuti nel payload di risposta dell'endpoint separato (vedi la sezione "Elenco dei partecipanti al gioco"). Questo collegamento è participantId proprietà presente in entrambi i payload. 

Cosa significa "risposta corretta"? 

Nel caso di alcuni tipi di domande, esiste una zona grigia tra lo stato di risposta "errata" e "corretta".

Domande a quiz a selezione multipla 

CORRETTO - il partecipante ha selezionato tutte le scelte corrette e nessuna di quelle sbagliate

PARZIALMENTE_CORRETTO - il partecipante ha selezionato almeno una delle scelte corrette e nessuna di quelle sbagliate SBAGLIATO - il partecipante ha selezionato almeno una delle scelte sbagliate

Domande sul cursore 

CORRETTO - il partecipante ha selezionato il valore corretto sul cursore

ALMOST_CORRECT - il partecipante ha selezionato un valore non esatto, ma all'interno della tolleranza impostata dal creatore del kahoot WRONG - il valore selezionato non rientrava nell'intervallo di tolleranza

Tutte le altre domande 

Per tutte le altre domande che possono risposte giuste o sbagliate, ci sono solo due possibilità: CORRETTO e SBAGLIATO.

Relazione tra il tempo di uscita e la risposta corretta 

Gli oggetti ParticipantAnswer con status uguale a TIMEOUT non avranno la proprietà answer , quindi non sono né "corretti" né "sbagliati".  Spetta all'utente decidere come trattarli. A loro vengono sempre assegnati zero punti durante la partita.

Presentazione dei dati API.

Ci sono molti modi per presentare i dati API estratti. Ecco un esempio di Kahoot! dati visualizzati in Power BI.

💡 Trovato utile? Iscrivetevi al nostro canale Youtube per altri suggerimenti e Kahoot! tutorial!