¡Guía de Kahoot! informes API

Actualización

¡¿Te preguntas cómo utilizar Kahoot! ¿Informes API? Aquí tienes todo lo que necesitas saber para empezar.

Accesos rápidos:

Acerca de la API de Kahoot 

La API de Kahoot es una API REST que sigue la OpenAPI. Puedes consultar toda la documentación de nuestra API, incluidos los detalles de los recursos y los puntos finales, en https://results.kahoot.com/swagger/. 

Para poder realizar llamadas a la API de Kahoot, tu empresa necesitará un acceso autorizado. La API es mejor para los clientes que tienen un equipo de datos o desarrolladores familiarizados con las API. Con esta API, tu empresa podrá acceder a todos los datos enumerados a continuación en los últimos 90 días tras la finalización del juego. Ponemos sellos de tiempo a nuestros datos y admitimos fechas de inicio y fin para cuando el cliente extrae los datos de nuestro sistema. 

La API de Kahoot proporciona información sobre el juego, los usuarios, los participantes, las organizaciones y los kahoots creados por la organización. A veces, nuestros informes en la plataforma no pueden hacer mucho. Para los clientes que utilizan el producto con frecuencia o con un número elevado de participantes, y quieren hacer un seguimiento de su actividad, la API es una forma estupenda de hacerlo de forma escalable.

Cómo acceder a la API

La autorización de la API sólo está disponible para los clientes de determinados planes de nivel superior. Ponte en contacto con tu gestor de éxito de clientes si estás interesado en actualizar o iniciar el proceso de autorización.

Autenticarse con la API

La autenticación para la API se consigue mediante el uso de un token portador JWT que debe proporcionarse en la cabecera de autenticación de cada solicitud a la API. Las fichas tienen un límite de tiempo de una hora, tras la cual hay que obtener una nueva ficha.

Para obtener un token necesitarás primero un identificador de cliente y un secreto que te proporcionará tu gestor de éxito del cliente. Una vez que dispongas de estas credenciales, deberás solicitar el token a nuestro servidor de autenticación, tal y como se describe a continuación.

URL

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

Método Http

PUT

Cabecera de autorización

Debe proporcionar un encabezamiento de autorización básico utilizando las credenciales proporcionadas por kahoot.

Cabecera Content-Type

application/x-www-form-urlencoded

Cuerpo de la solicitud

grant_type=credenciales_cliente

 

A continuación se muestra un ejemplo de solicitud que podría realizarse con curl:

curl --request POST \
--url https://access-2.kahoot.com/auth/realms/kahoot-api/protocol/openid-connect/token \
--header 'Autorización: Basic <digest>' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data grant_type=client_credentials

 

La respuesta de la solicitud tendrá la siguiente estructura:

{
"access_token": "<token to use in api requests>",
"expires_in": 3600,
"refresh_expires_in": 0,
"token_type": "Bearer",
"not-before-policy": 0,
"ámbito": "perfil de correo electrónico"
}

 

Para autenticarte correctamente en la API, debes utilizar el valor del access_token de la respuesta anterior como token portador en tus peticiones a la API. Esto significa que la cabecera Autorización de todas las solicitudes debe tener el valor "Portador: <token>". Si no has proporcionado correctamente un token válido a la API, se devolverá una respuesta 401.

Glosario

Plazo

Descripción

Juego en vivo

Cuando se juega un kahoot en persona.

Desafío

Cuando un kahoot se reproduce de forma asíncrona.

puntos

Valor entero. El número de puntos que el jugador ha obtenido por esta pregunta.

responde

Un conjunto de respuestas enviadas para una pregunta.

recibido, tiempo de espera

La respuesta dada a la pregunta.

tiempo de espera

Cuando un usuario no ha respondido a una pregunta.

Bloque

Los tipos específicos de preguntas siempre se denominan "bloque", por ejemplo: el tipo de pregunta Verdadero o Falso se denomina BloqueVerdaderoFalso y el tipo de pregunta Lluvia de ideas se denomina BloqueLluviaDeIneas.

kahoot

El kahoot real. Esto es diferente de una partida o sesión de juego (lo que llamamos cuando se juega realmente al kahoot).

Kahoot!.

Cuando se reproduce el kahoot.

sesión de juego

Una instancia de juego única.

alberga

El usuario que lanzó el juego.

versión kahoot

Si se modifican los kahoots, almacenamos diferentes versiones de ese kahoot. Se pueden jugar diferentes versiones de un kahoot y, por tanto, tener almacenadas diferentes respuestas. La versión del kahoot en la que se indica 0 no está versionada.

curso

Algunos juegos están vinculados a cursos, si éste es el caso se proporcionará un ID de curso.

Índice de bloques - Kahoot

Índice en el que apareció originalmente el juego en el kahoot asociado (basado en 0).

Índice de bloques - Juego

Índice en el que apareció el juego durante la sesión de juego (basado en 0).

Puede ser diferente de blockIndexInKahoot en caso de que se haya utilizado un orden aleatorio de las preguntas.

preguntas

Lista de preguntas del kahoot.

Lluvia de ideas (tipo pregunta)

Tipo de pregunta abierta en la que los participantes envían ideas y votan.

Drop Pin (tipo pregunta)

Pregunta sin puntos en la que los participantes pueden soltar chinchetas sobre una imagen.

Encuesta (tipo de pregunta)

Pregunta sin puntos en la que los jugadores eligen hasta 6 opciones en una pregunta.

Cuestionario multiselección (tipo de pregunta)

Da a los jugadores varias respuestas para elegir en una pregunta.

Abierta (tipo de pregunta)

Pregunta para que los jugadores respondan en un texto largo.

Puzzle (tipo pregunta)

Pregunta en la que los jugadores ponen las respuestas en el orden correcto.

Deslizador (tipo de pregunta)

Los participantes adivinan el número correcto dentro de un intervalo.

Verdadero Falso (tipo de pregunta)

Los participantes deciden si una afirmación es verdadera o falsa.

Tipo Respuesta (tipo de pregunta)

Los participantes responden con un texto breve.

Nube de palabras (tipo de pregunta)

Pregunta que recoge preguntas cortas de sondeo de forma libre.

Peticiones habituales - Guía práctica

Cómo hacer una lista de participantes en un juego

¿Quién es un "participante"? 

Los siguientes pasos describen cómo hacer una lista de todos los jugadores que entraron en la partida. 

Ten en cuenta que "unirse" no es lo mismo que "jugar activamente". Es posible unirse al juego y no responder a ninguna pregunta por problemas de conexión o por no prestar atención. Dichos participantes seguirán incluidos en los resultados. 

Encuentra el juego 

Invoca GET /v1/organisations/{organisationId}/games?limit={limit}&startedSince={date} para obtener una lista de todos los partidos jugados en tu organización en un periodo de tiempo determinado. Añade el parámetro de consulta cursor en caso de que haya otra página de resultados disponible y sea necesaria.

Un ejemplo de salida contendrá una lista de sesiones de juego:

{
datos: [
"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"
}

Busca la sesión en los resultados y recuerda que es gameSessionId. 

Lista de participantes en el juego 

Invoca GET /v1/organizaciones/{organisationId}/juegos/{gameSessionId}/participantes para obtener una lista de todos los participantes que se unieron al juego.

Resultado de la muestra: 

[

{

"participantId": 1234,

"apodo": "Johnny",

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

},

{

"participantId": 4321,

"apodo": "Robert",

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

}

]

¿Cuál es la diferencia entre participantId y userId? 

  • participantId es un número entero y siempre está presente, independientemente de las opciones del juego.
  • participantId identifica a un jugador determinado sólo dentro de esta sesión de juego. La misma participantId en una sesión de juego diferente puede y suele referirse a una persona distinta. 
  • userId sólo se incluye en los juegos con la opción Identificador de jugador activada. Es entonces cuando se pide a los jugadores que proporcionen sus credenciales, como el correo electrónico, además del apodo. O cuando se les invita al juego utilizando sus correos electrónicos.
  • userId permite seguir a la misma persona en varias sesiones de juego.

Cómo obtener la dirección de correo electrónico del participante 

Invocar GET /v1/organizaciones/{organisationId}/usuarios/{userId} El objeto devuelto contendrá correo electrónico propiedad. 

Cómo hacer una lista de los participantes que han acertado al menos el 80% de las preguntas 

Encuentra el juego

Consulta la sección sobre cómo encontrar el juego. 

Encuentra la información sobre el kahoot que se jugó. Tiene dos partes: 

  1. id - UUID que hace referencia al kahoot que se reprodujo
  1. versión - el kahoot podría haber sido editado por el creador después de que el juego tuviera lugar. Cada vez que eso ocurre se incrementa la propiedad versión. Esto garantiza que las respuestas se refieren a datos correctos.  
{

// otras propiedades

"kahootIdentifier": {

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

"version": 5

},

}

Consigue participantes

Consulta la sección sobre la lista de participantes.

Obtener datos de kahoot 

Invoca GET /v1/organizaciones/{organisationId}/kahoots/{kahootId}/versiones/{version} para obtener el kahoot con parámetros de consulta basados en las propiedades kahootIdentifier.id y kahootIdentifier.version . 

El resultado va a contener todas las preguntas (bloques) contenidas en el kahoot junto con las opciones de respuesta que estaban a disposición de los participantes, si procede. Las preguntas y las opciones de respuesta van a ser referenciadas posteriormente por los documentos de respuesta. 

Ejemplos de preguntas: 

{

"kahootIdentifier": {

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

"version": 5

},

"título": "Kahoot title",

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

"questions": [

{

"contentType": "CONTENT"

"blockIndex": 0

"title": "Esta es la presentación de la empresa"

"description": "Contenido de algunas diapositivas"

},

{

"contentType": "SINGLE_SELECT_QUIZ"

"blockIndex": 1

"question": "¿Quién es nuestro mayor cliente?" 

"opciones": [

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

{"answerText": "Skynet", "correcto": verdadero}

]

},

]

}

Obtén todas las respuestas 

Invoca GET /v1/organisations/{organisationId}/games/{gameSessionId}/blocks/{blockIndex}/answers utilizando gameSessi onId obtenido al buscar el juego (ver sección encontrar juego) y blockIndex siendo el índice de la pregunta en el kahoot. Hay que iterar sobre todos los bloques (preguntas) que se jugaron, excluyendo los que no eran preguntas en absoluto (contenido aka. diapositivas). 

El siguiente ejemplo muestra una respuesta al segundo bloque del kahoot, que era un cuestionario de selección única, en el que el participante se identificó con parti cipantId=1234 (apodo "Johnny" como en el ejemplo de los participantes de la lista ) y seleccionó la segunda opción, que resultó ser la correcta. También podemos ver que el participante con el apodo "Robert" no consiguió responder a la pregunta dentro del límite de tiempo.

{

"bloqueIndexInKahoot": 1

"respuestas": [

{

"participantId": 1234,

"answerStatus": "RECEIVED",

"answer": {

"tipo": "SINGLE_SELECT_QUIZ",

"elección": 1,

"correcto": verdadero,

"puntos": 900

}

},

{

"participantId": 4321,

"answerStatus": "TIMEOUT"

},

]

}

Para saber cuál fue la elección y cuál fue el apodo del participante hay que consultar los datos relacionados de kahoot y los datos del participante mencionados en secciones anteriores. 

¿Qué pasa si se devuelve 404? 

Las respuestas para un bloque determinado pueden faltar en los siguientes casos: 

  1. La pregunta dada (bloque) es del tipo CONTENIDO. "Responder" a ellas no está bien definido. 
  2. El juego se jugó como una tarea y ninguno de los participantes llegó a esa pregunta 3. 
  3. Hubo un problema de red durante el juego y no se guardó la respuesta (caso raro, pero puede ocurrir).

En cualquier caso, los clientes deben estar preparados para que los datos de respuesta puedan faltar allí. 

Hacer coincidir las respuestas con los participantes 

Las respuestas sólo contienen los enlaces a los participantes cuyos datos figuran en la carga útil de respuesta del punto final independiente (consulta la sección "Lista de participantes en el juego"). Ese enlace es participantId propiedad presente en ambas cargas útiles. 

¿Qué significa "respuesta correcta"? 

En el caso de algunos tipos de preguntas, existe una zona gris entre el estado de respuesta "incorrecta" y "correcta".

Preguntas del cuestionario de selección múltiple 

CORRECTO - el participante seleccionó todas las opciones correctas y ninguna de las incorrectas

PARCIALMENTE_CORRECTO - el participante seleccionó al menos una de las opciones correctas y ninguna de las incorrectas INCORRECTO - el participante seleccionó al menos una de las opciones incorrectas

Preguntas sobre la corredera 

CORRECTO - el participante seleccionó el valor correcto en el control deslizante

CASI CORRECTO - el participante seleccionó un valor que no era exacto, pero dentro de la tolerancia establecida por el creador del kahoot INCORRECTO - el valor seleccionado estaba fuera del rango de tolerancia

Todas las demás preguntas 

Para todas las demás preguntas que pueden tener respuestas correctas o incorrectas, sólo hay dos opciones: CORRECTA y INCORRECTA.

Relación entre el tiempo transcurrido y la respuesta correcta 

Los objetos ParticipantAnswer con estado igual a TIMEOUT no van a tener la propiedad answer , por lo que no son ni "correctos" ni "incorrectos".  Corresponde al usuario decidir cómo tratarlos. Siempre se les asignan cero puntos durante el juego.

Artículos relacionados

Informes

Artículos relacionados

Informes

0 comentarios

Inicie sesión para dejar un comentario.