Conecta Puzzel a tu propia plataforma

¿Qué canal necesitas?

De una actividad pueden salir tres cosas, y puede entrar una. Cuál te conviene depende de una sola pregunta: ¿el jugador está dentro de tu página, o en un sitio completamente distinto?

Webhook de resultados

Activa «Enviar los resultados a un webhook» en el editor y dale una URL. A partir de ahí, cada vez que se guarda el progreso del jugador, su navegador envía por POST el resultado completo a esa URL como JSON.

import express from 'express';

const app = express();

// The POST is made by the player's browser, so the browser asks permission
// first. Answer the preflight and the real request can land.
app.use((req, res, next) => {
  res.set('Access-Control-Allow-Origin', 'https://puzzel.org');
  res.set('Access-Control-Allow-Headers', 'Content-Type');
  if (req.method === 'OPTIONS') return res.sendStatus(204);
  next();
});

app.post('/puzzel/results', express.json(), async (req, res) => {
  const result = req.body;

  // One run posts several times as it goes. Key on the pair, not on an
  // insert: each call carries the whole state, so the newest simply wins.
  await db.results.upsert(
    { playerUid: result.playerUid, activityKey: result.activityKey },
    result
  );

  // Only act on the finish once.
  if (result.progress >= 100 || result.hasAlternateCompletion) {
    await markCourseStepComplete(result);
  }

  res.sendStatus(200);
});

Resultados a la página que la rodea

Si insertas la actividad, puedes hacer que ese mismo JSON se envíe a tu propia página en lugar de a un servidor. Activa «Enviar los resultados a la página principal» y escucha el mensaje. Nada sale del navegador, así que no hay ningún endpoint que construir ni CORS del que preocuparse.

<iframe
  src="https://puzzel.org/en/quiz/embed?p=-Nq8sample_activity_key"
  width="100%"
  height="700"
  frameborder="0"
  allowfullscreen
></iframe>

<script>
  window.addEventListener('message', (event) => {
    if (event.origin !== 'https://puzzel.org') return;

    const result = event.data;
    if (!result || !result.activityKey) return;

    // Same shape the webhook posts, same advice: it arrives repeatedly.
    saveProgress(result);
  });
</script>

Señal de finalización

El canal más pequeño, para cuando el resultado en sí no es asunto tuyo: activa «Enviar una señal de finalización» y tu página recibe un mensaje en el momento en que el jugador termina.

window.addEventListener('message', (event) => {
  if (event.origin !== 'https://puzzel.org') return;
  if (event.data?.completed !== true) return;

  // { completed: true, activityKey: '-Nq8sample_activity_key' }
  unlockNextLesson(event.data.activityKey);
});

{
  "completed": true,
  "activityKey": "-Nq8sample_activity_key"
}

Qué contiene un resultado

Una sola forma, sea cual sea el canal que la lleve. Las respuestas del jugador tienen como clave los ids propios de cada elemento de la actividad, así que esas mismas claves aparecen en correctUids.

{
  "activityKey": "-Nq8sample_activity_key",
  "playerUid": "kK3r9TzSampleAnonymousUid",
  "player": {
    "name": "Ava Ortega",
    "email": "ava@school.example",
    "class": "5B"
  },
  "progress": 100,
  "timePassed": 243120,
  "lastPlayedAt": 1758297843120,
  "createdAt": 1758297600000,
  "playerInput": {
    "-Nq8item_one": "Lisbon",
    "-Nq8item_two": "1969"
  },
  "correctUids": {
    "-Nq8item_one": true,
    "-Nq8item_two": false
  },
  "score": 800,
  "contentVersion": 1757923200000
}

Reiniciar la actividad desde tu página

Una instrucción viaja en sentido contrario. Con «Aceptar órdenes de la página principal» activado, la página que hace la inserción puede borrar las respuestas del jugador y volver a poner la actividad al principio —para un botón «intentar de nuevo» propio, fuera del marco.

const frame = document.querySelector('iframe').contentWindow;

// Sent to the frame, from the page that embeds it — no other sender is
// accepted, and the activity has to have the trigger setting switched on.
frame.postMessage({ trigger: { type: 'reset' } }, 'https://puzzel.org');

Aportar tu propia identidad de jugador

Si tu plataforma ya sabe quién está jugando, la actividad no tiene que volver a preguntárselo. Existen dos protocolos de enlace, ambos para una actividad dentro de tu página, y ambos los activamos nosotros en lugar del editor —cambian a quién pertenece un resultado, así que se configuran contigo y no desde una casilla.

window.addEventListener('message', (event) => {
  if (event.origin !== 'https://puzzel.org') return;

  // The activity says it is ready for a player.
  if (event.data === 'app-loaded') {
    frame.postMessage(
      {
        player: { name: 'Ava Ortega', email: 'ava@school.example', class: '5B' },
        // true starts a fresh attempt instead of resuming this player's last one
        should_reset: false
      },
      'https://puzzel.org'
    );
  }

  // Signed in; the board is coming.
  if (event.data?.success === true) hideYourOwnSpinner();
});

Crear actividades desde tu sistema

Todo lo anterior trata de un resultado que sale. En sentido contrario —crear las actividades a partir de contenido que ya tienes— está la Puzzle API: un POST por tipo de actividad, y recibes de vuelta una clave y una URL para insertar.

Cuando un conector ya hecho es la mejor opción

Si la plataforma del otro lado es un LMS de verdad, probablemente no necesites nada de esto. Las calificaciones pueden volver solas a su libro de calificaciones, sin que tengas que alojar nada.

Lo que no hay

Para que no lo busques donde no está:

• No hay ningún endpoint para leer los resultados de vuelta. La API crea actividades; los resultados salen por los canales de esta página, o por las exportaciones de tu panel.
• El webhook no lleva firma. No hay nada contra lo que verificar la solicitud, por eso un resultado no debería ser lo único que respalde algo importante.
• No hay ningún webhook a nivel de cuenta. La URL es un ajuste de cada actividad, así que una actividad que copias lo lleva consigo y una nueva empieza sin él.
• Nada en un juego por equipos o una sala en directo. Tanto los canales de mensajes como el webhook son para juego individual, y los ajustes se desactivan solos cuando el juego por equipos está activado.
• No hay ninguna cola de entrega. Nada se almacena ni se reenvía —el siguiente guardado es el reintento, y la última llamada de la partida es la que cuenta.