Guia para Kahoot! relatórios API

Atualizado

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

Atalhos:

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 . 

A fim de fazer chamadas para Kahoot API a sua empresa necessitará 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. 

O Kahoot API informa sobre informações relativas ao jogo, utilizadores, participantes, organizações, e kahoots criados pela organização. Por vezes, os nossos relatórios sobre a plataforma não podem fazer muito mais que isso. Para os clientes que utilizam o produto frequentemente ou com um elevado número de participantes, e que querem acompanhar a sua actividade, o API é uma óptima forma de o fazer 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 para a API é conseguida através da utilização de um token portador do TPJ que deve ser fornecido no cabeçalho da autenticação de cada pedido à API. Os tokens são limitados a uma hora após a qual um novo token deve ser obtido.

Para obter uma ficha, necessitará primeiro de uma identificação e segredo de cliente que será fornecido pelo seu gestor de sucesso de cliente. Assim que tiver estas credenciais deverá solicitar o token ao nosso servidor de autenticação, conforme descrito abaixo.

URL

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

Método Http

PUT

Cabeçalho de Autorização

Deve fornecer uma rubrica de autorização básica utilizando as credenciais fornecidas pela kahoot.

Cabeçalho Tipo Content-Type

aplicação/x-www-form-urlencoded

Corpo do Pedido

grant_type=client_credentials

 

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

encaracolar --pedido POST \
--url \
--header 'Autorização: 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 to use in api requests>",
"expira_em": 3600,
"refresh_expires_in": 0,
"token_type": ": "Bearer",
"not-before-policy": 0,
"escopo": "perfil de e-mail":
}

 

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

Termo

Descrição

Jogo ao vivo

Quando um kahoot é jogado em pessoa.

Desafio

Quando um kahoot é jogado de forma assíncrona.

points

Valor inteiro. O número de pontos que o jogador obteve para esta pergunta.

respostas

Um conjunto de respostas submetidas para uma pergunta.

recebido, tempo esgotado

A resposta à pergunta foi dada.

tempo esgotado

Quando um utilizador não forneceu uma resposta a uma pergunta.

Bloco

Tipos específicos de perguntas são sempre referidos como 'bloco', por exemplo - o tipo de pergunta Verdadeiro ou Falso é chamado TrueFalseBlock e o tipo de pergunta BrainstormBlock é referido como BrainstormBlock.

kahoot

O verdadeiro kahoot. Isto é diferente de um jogo ou sessão de jogo (o que chamamos quando o kahoot é realmente jogado).

kahoots.

Quando o kahoot é jogado.

sessão de jogo

Uma instância de jogo única.

organizar

O utilizador que lançou o jogo.

versão kahoot

Se os kahoots forem modificados, armazenamos diferentes versões desse kahoot. Diferentes versões de um kahoot podem ser jogadas e assim ter diferentes respostas armazenadas. A versão do kahoot onde 0 é indicado não está versionada.

curso

Alguns jogos estão ligados a cursos, se for este o caso, será fornecida uma identificação do curso.

Índice de blocos - Kahoot

Índice em que o jogo apareceu originalmente no kahoot associado (baseado em 0).

Índice de blocos - Jogo

Índice em que o jogo apareceu durante a sessão de jogo (com base em 0).

Pode ser diferente do blocoIndexInKahoot no caso de ter sido utilizada uma ordem aleatória de perguntas.

perguntas

Lista de perguntas no kahoot.

Brainstorm (tipo de pergunta)

Tipo de pergunta aberta em que os participantes submetem ideias e votam.

Pino de gota (tipo de pergunta)

Pergunta sem pontos em que os participantes podem largar pinos numa imagem.

Sondagem (tipo de pergunta)

Pergunta sem pontos em que os jogadores escolhem até 6 opções numa pergunta.

Quiz Multiselect (tipo de pergunta)

Dar aos jogadores várias respostas a escolher numa pergunta.

Aberto (tipo de pergunta)

Pergunta para os jogadores responderem em texto de forma longa.

Puzzle (tipo de pergunta)

Pergunta onde os jogadores colocam as respostas na ordem correcta.

Deslizador (tipo de pergunta)

Os participantes adivinham o número correcto num intervalo.

Verdadeiro Falso (tipo de pergunta)

Os participantes decidem se uma declaração é verdadeira ou falsa.

Tipo Resposta (tipo de pergunta)

Os participantes respondem com um breve texto de formulário.

Nuvem de palavras (tipo de pergunta)

Pergunta que recolhe perguntas breves de sondagens de forma livre.

Pedidos comuns - Como orientar

Como listar os participantes de um jogo

Quem é um "participante"? 

Os passos seguintes descrevem como listar todos os jogadores que entraram no jogo. 

Note-se que "aderir" não é o mesmo que "jogar activamente". É 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 saída de amostra conterá uma lista de sessões de jogo:

{
dados: {
"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.

Resultado da amostra: 

[

{

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

"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 vai conter todas as questões (blocos) contidas pelo kahoot juntamente com as escolhas de resposta que estavam disponíveis para os participantes, se aplicável. As perguntas e opções de resposta serão posteriormente referenciadas pelos documentos de resposta. 

Exemplos de perguntas: 

{

"kahootIdentifier": {

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

"version": 5

},

"title": "título": "Kahoot",

"descrição": "Este kahoot é sobre ...",

"perguntas": [

{

"contentType": "CONTEÚDO":

"blockIndex": 0

"título": "This is the company presentation":

"description": "Some slide contents":

},

{

"contentType": "SINGLE_SELECT_QUIZ":

"blockIndex": 1

"pergunta": "Quem é o nosso maior cliente?" 

"escolhas": [

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

{"answerText": "Very Big Corp. of America", "correct": falso", {"answerText": "answerText": "Skynet", "correcto": verdadeiro}, ["answerText": verdadeiro

]

},

]

}

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 seguinte mostra uma resposta ao segundo bloco do kahoot que foi um único teste selectivo, onde o participante se identificou com parti cipantId=1234 (nickname "Johnny" como no exemplo listando os participantes) e seleccionou a segunda escolha que por acaso estava correcta. Também podemos ver que o participante com o apelido "Robert" não conseguiu responder à pergunta dentro do tempo limite.

{

"blockIndexInKahoot": 1

"responde": {

{

"participantId": 1234,

"answerStatus": "RECEBIDO",

"resposta": {

"tipo": "SINGLE_SELECT_QUIZ",

"escolha": 1,

"correcto": verdadeiro,

"pontos": 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".

Perguntas de questionário de selecção múltipla 

CORRECTO - o participante seleccionou todas as escolhas correctas e nenhuma das erradas

PARTIALLY_CORRECT - o participante seleccionou pelo menos uma das escolhas correctas e nenhuma das escolhas erradas ERRADO - o participante seleccionou pelo menos uma das escolhas erradas

Perguntas com controle deslizante 

CORRECTO - o participante seleccionou o valor correcto no selector

ALMOST_CORRECT - o participante seleccionou um valor que não era exacto, mas dentro da tolerância definida pelo criador do kahoot WRONG - o valor seleccionado estava fora do intervalo de tolerância

Todas as outras questões 

Para todas as outras perguntas que pode tem respostas certas ou erradas, há apenas duas opções: CORRECTO 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.

Artigos relacionados

Relatórios

Artigos relacionados

Relatórios

0 comentário

Por favor, entre para comentar.