Guida a Kahoot! rapporti API

Aggiornato

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

Accesso rapido:

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.

URL

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

Metodo Http

INVIO

Intestazione di autorizzazione

Deve fornire un'autorizzazione di base utilizzando le credenziali fornite da kahoot.

Intestazione Content-Type

applicazione/x-www-form-urlencoded

Corpo della richiesta

grant_type=client_credentials

 

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 to use in api requests>",
"expires_in": 3600,
"refresh_expires_in": 0,
"token_type": "Bearer",
"not-before-policy": 0,
"scope": "profilo email"
}

 

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

Termine

Descrizione

Gioco in diretta

Quando un kahoot viene giocato di persona.

Sfida

Quando un kahoot viene riprodotto in modo asincrono.

punti

Valore intero. Il numero di punti ottenuti dal giocatore per questa domanda.

risposte

Un insieme di risposte inviate per una domanda.

ricevuto, timeout

La risposta fornita per la domanda.

timeout

Quando un utente non ha fornito una risposta a una domanda.

Blocco

I tipi specifici di domande sono sempre indicati con il termine "blocco": ad esempio, il tipo di domanda Vero o Falso si chiama VeroFalsoBlocco e il tipo di domanda Brainstorm si chiama BrainstormBlocco.

kahoot

Il kahoot vero e proprio. Questo è diverso da un gioco o da una sessione di gioco (come si chiama quando il kahoot viene effettivamente giocato).

Kahoot!.

Quando il kahoot viene giocato.

sessione di gioco

Un'istanza di gioco unica.

ospite

L'utente che ha lanciato il gioco.

Versione kahoot

Se i kahoot vengono modificati, memorizziamo diverse versioni di quel kahoot. Possono essere giocate diverse versioni di un kahoot e quindi possono essere memorizzate risposte diverse. La versione del kahoot in cui è indicato 0 non è dotata di versione.

corso

Alcuni giochi sono legati a dei corsi, in questo caso verrà fornito un ID del corso.

Indice dei blocchi - Kahoot

Indice in cui il gioco è apparso originariamente nel kahoot associato (basato su 0).

Indice dei blocchi - Gioco

Indice in cui il gioco è apparso durante la sessione di gioco (basato su 0).

Può essere diverso da blockIndexInKahoot nel caso in cui sia stato utilizzato un ordine casuale delle domande.

domande

Elenco delle domande del kahoot.

Brainstorm (tipo di domanda)

Tipo di domanda aperta in cui i partecipanti inviano idee e votano.

Spillo a goccia (tipo di domanda)

Domanda senza punti in cui i partecipanti possono lasciare dei puntini su un'immagine.

Sondaggio (tipo di domanda)

Domanda senza punti in cui i giocatori scelgono fino a 6 opzioni in una domanda.

Quiz a selezione multipla (tipo di domanda)

Dai ai giocatori diverse risposte tra cui scegliere in una domanda.

A risposta aperta (tipo di domanda)

Domanda a cui i giocatori devono rispondere con un testo lungo.

Puzzle (tipo di domanda)

Domanda in cui i giocatori inseriscono le risposte nell'ordine corretto.

Cursore (tipo di domanda)

I partecipanti indovinano il numero corretto in un intervallo.

Vero Falso (tipo di domanda)

I partecipanti decidono se un'affermazione è vera o falsa.

Tipo Risposta (tipo di domanda)

I partecipanti rispondono con un breve testo.

Nuvola di parole (tipo di domanda)

Domanda che raccoglie brevi domande di sondaggio in forma libera.

Richieste comuni - Guida alle modalità

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
  1. 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

},

"titolo": "Titolo del kahoot",

"descrizione": "Questo kahoot riguarda ...",

"domande": [

{

"contentType": "CONTENT"

"blockIndex": 0

"title": "Questa è la presentazione dell'azienda"

"description": "Alcuni contenuti delle diapositive"

},

{

"contentType": "SINGLE_SELECT_QUIZ"

"blockIndex": 1

"domanda": "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",

"scelta": 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 avere risposte giuste o sbagliate, ci sono solo due scelte: CORRETTA e SBAGLIATA.

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.

Articoli correlati

Statistiche

Articoli correlati

Statistiche

0 commenti

Accedi per aggiungere un commento.