¡Guía de Kahoot! informes API

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

• Acerca de la API de Kahoot
• Cómo acceder a la API
• Autenticarse con la API
• Glosario
• Peticiones habituales - Guía práctica

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, su empresa necesitará 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 relativa al juego, a los usuarios, a los participantes, a las organizaciones y a 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 gran número de participantes y desean realizar un seguimiento de su actividad, la API es una forma estupenda de hacerlo de manera 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 en la API se lleva a cabo mediante un token JWT de tipo «bearer», que debe incluirse en el encabezado «Authentication» de cada solicitud enviada a la API. Las fichas tienen una validez limitada de una hora; transcurrido ese tiempo, hay que obtener una nueva ficha.

Para obtener un token, primero necesitarás un ID de cliente y una clave secreta, que te facilitará 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.

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 a usar en peticiones api>",
"expires_in": 3600,
"refresh_expires_in": 0,
"token_type": "Bearer",
"not-before-policy": 0,
"scope": "email profile"
}

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

Peticiones habituales - Guía práctica

• Cómo hacer una lista de participantes en un juego
• ¿Quién es un "participante"? 
• Encuentra el juego
• ¿Cuál es la diferencia entre participantId y userId? 
• Cómo obtener la dirección de correo electrónico del participante
• Cómo hacer una lista de los participantes que han acertado al menos el 80% de las preguntas
• ¿Qué pasa si se devuelve 404? 
• Hacer coincidir las respuestas con los participantes 
• ¿Qué significa "respuesta correcta"?
• Relación entre el tiempo transcurrido y la respuesta correcta

Cómo hacer una lista de participantes en un juego

¿Quién es un "participante"? 

Los siguientes pasos describen cómo mostrar una lista de todos los jugadores que se han unido a 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.

Ejemplo de resultado: 

[

{

"participantId": 1234,

"nickname": "Johnny",

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

},

{

"participantId": 4321,

"nickname": "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
2. 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 incluirá todas las preguntas (bloques) que contiene el Kahoot, junto con las opciones de respuesta que estaban disponibles para 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

},

"title": "Kahoot title",

"description": "This kahoot is about ...",

"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?" 

 "choices": [

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

{"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 consistía en un cuestionario de selección única, en el que el participante identificado con participantId=1234 (apodo «Johnny», tal y como aparece en el ejemplo de la lista de participantes) 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.

{

"blockIndexInKahoot": 1

"answers": [

{

"participantId": 1234,

"answerStatus": "RECEIVED",

"answer": {

"type": "SINGLE_SELECT_QUIZ",

"choice": 1,

"correct": true,

"points": 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 de examen con selección múltiple 

CORRECTO - el participante ha seleccionado todas las opciones correctas y ninguna de las incorrectas 

PARCIALMENTE_CORRECTO - el participante ha seleccionado al menos una de las opciones correctas y ninguna de las incorrectas INCORRECTO - el participante ha seleccionado al menos una de las respuestas incorrectas 

Preguntas con control deslizante 

CORRECTO - el participante ha seleccionado el valor correcto en el control deslizante 

CASI_CORRECTO - El participante ha seleccionado un valor que no es exacto, pero que se encuentra dentro del margen de tolerancia establecido por el creador de Kahoot INCORRECTO - El valor seleccionado se encontraba fuera del rango de tolerancia

Cualquier otra pregunta 

Para cualquier otra pregunta que pueden tener respuestas correctas o incorrectas, solo hay dos opciones: CORRECTA y INCORRECTO.

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.

Presentación de los datos de la API

Hay muchas formas de presentar los datos extraídos de la API. ¡Aquí tienes un ejemplo de Kahoot! datos visualizados en Power BI.

💡 ¿Te ha resultado útil? ¡Suscríbete a nuestro canal de Youtube para recibir más consejos y Kahoot! ¡tutoriales!