Guida a Kahoot! rapporti API

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

• 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 richieste all'API di Kahoot, la vostra azienda dovrà disporre di 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 fornisce 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 desiderano monitorarne l’attività, l’API rappresenta un ottimo strumento 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 tramite l'uso di un token JWT di tipo "bearer", che deve essere indicato nell'intestazione "Authentication" di ogni richiesta inviata all'API. I token hanno una validità limitata a un'ora; trascorso tale tempo, è necessario ottenerne uno nuovo.

Per ottenere un token, dovrai innanzitutto disporre di un ID cliente e di una chiave segreta, che ti saranno forniti dal tuo responsabile del customer success. Una volta ottenute queste credenziali, è necessario 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 passaggi seguenti spiegano come visualizzare l'elenco di tutti i giocatori che hanno partecipato alla partita. 

Si prega di notare 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.

Esempio di risultato: 

[

{

"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) presenti nel Kahoot, insieme alle opzioni di risposta che erano a disposizione dei partecipanti, se del caso. Le domande e le opzioni di risposta saranno successivamente referenziate dai documenti di risposta. 

Esempi di domande: 

{

"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 consisteva in un quiz a scelta singola, in cui il partecipante identificato con participantId=1234 (nickname “Johnny”, come nell'esempio dell'elenco dei partecipanti) ha selezionato la seconda opzione, 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 risposta multipla 

CORRETTO - il partecipante ha selezionato tutte le risposte corrette e nessuna di quelle errate 

PARZIALMENTE_CORRETTO - il partecipante ha selezionato almeno una delle risposte corrette e nessuna di quelle errate ERRATO - il partecipante ha selezionato almeno una delle risposte errate 

Domande a scorrimento 

CORRETTO - il partecipante ha selezionato il valore corretto sul cursore 

QUASI_CORRETTO - il partecipante ha selezionato un valore non esatto, ma compreso entro il margine di tolleranza impostato dal creatore di Kahoot ERRATO - il valore selezionato era al di fuori dell’intervallo di tolleranza

Tutte le altre domande 

Per tutte le altre domande che possono avere risposte giuste o sbagliate, ci sono solo due opzioni: CORRETTA 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 dell'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!