Guia para Kahoot! relatórios API

A pensar como usar Kahoot! relata API? Aqui está tudo o que precisa de saber para começar.

• Sobre o Kahoot API
• Como aceder ao API
• Autenticação com a API
• Glossário
• Pedidos comuns - Como orientar

Sobre o Kahoot API 

O Kahoot API é um REST API que segue o OpenAPI. Pode rever toda a nossa documentação API incluindo detalhes dos recursos e dos pontos finais em . 

Para fazer chamadas à API do Kahoot, sua empresa precisará de acesso autorizado. O API é melhor para clientes que tenham uma equipa de dados ou desenvolvedores que estejam familiarizados com APIs. Com esta API a sua empresa poderá aceder a todos os dados listados abaixo dentro dos últimos 90 dias após o fim do jogo. Marcamos as datas de início e fim dos nossos dados e de suporte para quando o cliente retira os dados do nosso sistema. 

A API do Kahoot fornece informações relacionadas ao jogo, aos usuários, aos participantes, às organizações e aos kahoots criados pela organização. Por vezes, os nossos relatórios sobre a plataforma não podem fazer muito mais que isso. Para clientes que utilizam o produto com frequência ou com um grande número de participantes e desejam acompanhar suas atividades, a API é uma excelente maneira de fazer isso de forma escalável.

Como aceder ao API

A autorização do API só está disponível para clientes em certos planos de alto nível. Contacte o seu gestor de sucesso de clientes se estiver interessado em actualizar ou iniciar o processo de autorização.

Autenticação com a API

A autenticação na API é realizada por meio do uso de um token JWT do tipo “bearer”, que deve ser fornecido no cabeçalho “Authentication” de cada solicitação enviada à API. Os tokens têm validade limitada a uma hora; após esse período, é necessário obter um novo token.

Para obter um token, você precisará primeiro de um ID de cliente e de um segredo, que serão fornecidos pelo seu gerente de sucesso do cliente. Depois de obter essas credenciais, você deverá solicitar o token ao nosso servidor de autenticação, conforme descrito a seguir.

Um exemplo de pedido que poderia ser feito com o encaracolamento é mostrado abaixo:

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

A resposta do pedido terá a seguinte estrutura:

{
"access_token": "<token para usar em solicitações de API>",
"expires_in": 3600,
"refresh_expires_in": 0,
"token_type": "Bearer",
"not-before-policy": 0,
"scope": "email profile"
}

Para autenticar correctamente a API deve utilizar o valor do access_token na resposta acima referida como um token portador nos seus pedidos à API. Isto significa que o cabeçalho de Autorização de todos os pedidos deve ter o valor sob a forma de "Portador": <token>”. Se não tiver fornecido correctamente uma ficha válida à API, será devolvida uma resposta 401.

Glossário

Pedidos comuns - Como orientar

• Como listar os participantes de um jogo
• Quem é um "participante"? 
• Encontrar o jogo
• Qual é a diferença entre participantId e userId? 
• Como obter o endereço electrónico do participante
• Como listar os participantes que acertaram pelo menos 80% das perguntas
• E se o 404 for devolvido? 
• Correspondência das respostas com os participantes 
• O que significa "resposta correcta"?
• Relação entre o tempo esgotado e a resposta correta

Como listar os participantes de um jogo

Quem é um "participante"? 

As etapas a seguir descrevem como listar todos os jogadores que entraram no jogo. 

Observe que “participar” não é o mesmo que “jogar ativamente”. É possível entrar no jogo e não responder a quaisquer perguntas devido a problemas de ligação ou não prestar atenção. Tais participantes vão continuar a ser incluídos nos resultados. 

Encontrar o jogo 

Invoque GET /v1/organisationss/{organisationId}/games?limit={limit}&startedSince={date} para listar todos os jogos jogados na sua organização num determinado período de tempo. Adicionar cursor parâmetro de consulta no caso de outra página de resultados estar disponível e ser necessária.

Uma amostra da saída conterá uma lista de sessões de jogo:

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

Encontre a sessão nos resultados e lembre-se que é gameSessionId. 

Lista dos participantes do jogo 

Convocar GET /v1/organizações/{organisationId}/games/{gameSessionId}/participantes para listar todos os participantes que aderiram ao jogo.

Exemplo de resultado: 

[

{

"participantId": 1234,

"nickname": "Johnny",

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

},

{

"participantId": 4321,

"nickname": "Robert",

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

}

]

Qual é a diferença entre participantId e userId? 

• participantId é um número inteiro e está sempre presente independentemente das opções de jogo.
• participanteId identifica um determinado jogador apenas dentro desta sessão de jogo. O mesmo participanteId numa sessão de jogo diferente pode e normalmente refere-se a uma pessoa diferente. 
• userId só está incluído em jogos com a opção Player Identifier activada. É quando se pede aos jogadores que forneçam as suas credenciais, tais como e-mail, para além do apelido. Ou quando são convidados para o jogo utilizando os seus e-mails.
• userId torna possível seguir a mesma pessoa através de múltiplas sessões de jogo.

Como obter o endereço electrónico do participante 

Invoke GET /v1/organisationss/{organisationId}/users/{userId} O objecto devolvido conterá e-mail propriedade. 

Como listar os participantes que acertaram pelo menos 80% das perguntas 

Encontrar o jogo

Ver a secção sobre como encontrar o jogo. 

Encontrar a informação sobre o kahoot que foi jogado. Tem duas partes: 

1. id - UUID referenciando o kahoot que foi jogado
2. versão - o kahoot pode ter sido editado pelo criador após a realização do jogo. Cada vez que isso acontece, a propriedade da versão é incrementada. Isto assegura que as respostas se referem a dados correctos. 

{

// outras propriedades

"kahootIdentifier": {

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

"version": 5

},

}

Conseguir participantes

Ver a secção sobre a listagem dos participantes.

Obter dados kahoot 

Invoque GET /v1/organisations/{organisationId}/kahoots/{kahootId}/versions/{version} para obter o kahoot com parâmetros de consulta baseados em kahootIdentifier.id e kahootIdentifier.version propriedades. 

O resultado conterá todas as perguntas (blocos) do Kahoot, juntamente com as opções de resposta que estavam disponíveis para os participantes, se for o caso. As perguntas e opções de resposta serão posteriormente referenciadas pelos documentos de resposta. 

Exemplos de questões: 

{

"kahootIdentifier": {

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

"version": 5

},

"title": "Kahoot title",

"description": "Este kahoot é sobre ...",

"questions": [

{

"contentType": "CONTENT"

"blockIndex": 0

"title": "Esta é a apresentação da empresa"

"description": "Some slide contents"

},

{

"contentType": "SINGLE_SELECT_QUIZ"

"blockIndex": 1

"question": "Quem é nosso maior cliente?" 

 "choices": [

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

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

]

},

]

}

Obter todas as respostas 

Invoque GET /v1/organisationss/{organisationId}/games/{gameSessionId}/blocks/{blockIndex}/answers usando gameSessi onId obtido ao procurar o jogo (ver secção encontrar jogo) e blockIndex sendo o índice da questão no kahoot. É preciso iterar sobre todos os blocos (perguntas) que foram jogados, excluindo os que não eram perguntas de todo (conteúdo também conhecido por "content aka"). diapositivos). 

O exemplo a seguir mostra uma resposta ao segundo bloco do Kahoot, que era um questionário de escolha única, no qual o participante identificado com participantId=1234 (apelido “Johnny”, conforme o exemplo da lista de participantes em ) selecionou a segunda opção, que por acaso estava correta. Também podemos ver que o participante com o apelido "Robert" não conseguiu responder à pergunta dentro do tempo limite.

{

"blockIndexInKahoot": 1

"answers": [

{

"participantId": 1234,

"answerStatus": "RECEIVED",

"answer": {

"type": "SINGLE_SELECT_QUIZ",

"choice": 1,

"correct": true,

"points": 900

}

},

{

"participantId": 4321,

"answerStatus": "TIMEOUT"

},

]

}

A fim de saber qual foi a escolha e qual foi o apelido do participante é necessário consultar kahoot data e os dados do participante mencionados nas secções anteriores. 

E se o 404 for devolvido? 

As respostas para um determinado bloco podem estar em falta nos seguintes casos: 

1. A pergunta dada (bloco) é do tipo CONTEÚDO. A "resposta" não está bem definida. 
2. O jogo foi jogado como uma missão e nenhum dos participantes chegou a essa pergunta 3. 
3. Houve um problema de rede durante o jogo e a resposta não foi salva (caso raro, mas possível de acontecer).

Em qualquer caso, os clientes precisam de estar preparados para que os dados de resposta possam estar em falta. 

Correspondência das respostas com os participantes 

As respostas contêm apenas os links para os participantes cujos detalhes estão contidos na carga útil de resposta do ponto final separado (ver secção "Listar os participantes do jogo"). Essa ligação é participantId propriedade presente em ambas as cargas úteis. 

O que significa "resposta correcta"? 

No caso de alguns tipos de perguntas, existe alguma área cinzenta entre o estado de resposta "incorrecta" e "correcta".

Questões de múltipla escolha 

CORRETO - o participante selecionou todas as opções corretas e nenhuma das erradas 

PARCIALMENTE_CORRETO - o participante selecionou pelo menos uma das opções corretas e nenhuma das erradas ERRADO - o participante selecionou pelo menos uma das opções erradas 

Perguntas com controle deslizante 

CORRETO - o participante selecionou o valor correto no controle deslizante 

QUASE_CORRETO - o participante selecionou um valor que não era exato, mas estava dentro da tolerância definida pelo criador do Kahoot ERRADO - o valor selecionado estava fora do intervalo de tolerância

Todas as outras perguntas 

Para todas as outras dúvidas que possam ter respostas certas ou erradas, há apenas duas opções: CORRETO e ERRADO.

Relação entre a resposta correcta e a resposta atempada 

ParticipantAnswer objectos com estatuto igual a TIMEOUT não vão ter resposta propriedade, pelo que não são nem "correctos" nem "errados".  Cabe ao utilizador decidir como tratá-los. São-lhes sempre atribuídos pontos zero durante o jogo.

Apresentação dos dados da API

Há muitas maneiras de apresentar dados de API extraídos. Aqui está um exemplo do Kahoot! dados visualizados no Power BI.

Achou isso útil? Inscreva-se em nosso canal do YouTube para obter mais dicas e Kahoot! tutoriais!