Connecte Puzzel à ta propre plateforme

De quel canal as-tu besoin ?

Trois choses peuvent sortir d'une activité et une seule peut y entrer. Le bon choix dépend d'une seule question : le joueur se trouve-t-il dans ta page, ou complètement ailleurs ?

Webhook de résultats

Active "Envoyer les résultats à un webhook" dans l'éditeur et indique une URL. À partir de là, chaque fois que la progression du joueur est enregistrée, son navigateur envoie l'ensemble du résultat en POST vers cette URL, au format 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);
});

Résultats vers la page qui l'héberge

Si tu intègres l'activité, tu peux faire envoyer ce même JSON à ta propre page plutôt qu'à un serveur. Active "Envoyer les résultats à la page parente" et écoute le message. Rien ne sort du navigateur, donc aucun point de terminaison à construire et aucun CORS à gérer.

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

Signal de fin

Le plus petit canal, pour quand le résultat lui-même ne te regarde pas : active "Envoyer un signal de fin" et ta page reçoit un message dès que le joueur termine.

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

Ce que contient un résultat

Une seule structure, quel que soit le canal qui la transporte. Les réponses du joueur sont indexées par les identifiants propres des éléments de l'activité, donc les mêmes clés se retrouvent dans 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
}

Réinitialiser l'activité depuis ta page

Une instruction circule dans l'autre sens. Avec "Accepter les commandes de la page parente" activé, la page qui fait l'intégration peut effacer les réponses du joueur et remettre l'activité à son point de départ — pour ton propre bouton "réessayer", en dehors du cadre.

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');

Utiliser ta propre identité de joueur

Si ta plateforme sait déjà qui joue, l'activité n'a pas besoin de le redemander. Deux échanges existent, tous deux pour une activité intégrée dans ta page, et tous deux activés par nous plutôt que dans l'éditeur — ils déterminent à qui appartient un résultat, donc ils se mettent en place avec toi plutôt que depuis une case à cocher.

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();
});

Créer des activités depuis ton système

Tout ce qui précède concerne un résultat qui sort. Faire l'inverse — créer les activités elles-mêmes à partir de contenu que tu possèdes déjà — c'est le rôle de la Puzzle API : un POST par type d'activité, et tu récupères une clé et une URL à intégrer.

Quand un connecteur tout prêt est la meilleure solution

Si la plateforme en face est un vrai LMS, tu n'as probablement besoin de rien de tout ça. Les notes peuvent remonter d'elles-mêmes dans son carnet de notes, sans rien à héberger de ton côté.

Ce qu'il n'y a pas

Pour que tu ne le cherches pas en vain :

• Aucun point de terminaison pour relire les résultats. L'API crée des activités ; les résultats sortent par les canaux de cette page, ou par les exports de ton tableau de bord.
• Aucune signature sur le webhook. Il n'y a rien pour vérifier la requête, c'est pourquoi un résultat ne devrait jamais être la seule chose garantissant quelque chose d'important.
• Aucun webhook valable pour tout le compte. L'URL est un paramètre de l'activité, donc une activité copiée l'emporte avec elle et une nouvelle activité démarre sans.
• Rien dans un jeu en équipes ou une salle en direct. Les deux canaux de messages et le webhook sont réservés au jeu en solo, et les paramètres se désactivent d'eux-mêmes quand le mode équipes est actif.
• Aucune file d'attente de livraison. Rien n'est stocké puis renvoyé — le prochain enregistrement fait office de nouvelle tentative, et c'est le dernier appel de la partie qui compte.