Verbind Puzzel met je eigen platform

Welk kanaal heb je nodig?

Drie dingen kunnen een activiteit verlaten en één kan erin. Welke bij jou past hangt af van één vraag: zit de speler binnen jouw pagina, of ergens heel anders?

Resultaten-webhook

Zet "Resultaten naar een webhook sturen" aan in de editor en geef er een URL bij op. Vanaf dan post de browser van de speler bij elke keer dat de voortgang wordt opgeslagen het hele resultaat als JSON naar die URL.

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

Resultaten naar de omliggende pagina

Sluit je de activiteit in, dan kun je diezelfde JSON naar je eigen pagina laten posten in plaats van naar een server. Zet "Resultaten naar de bovenliggende pagina sturen" aan en luister naar het bericht. Er verlaat niets de browser, dus je hoeft geen endpoint te bouwen en niet aan CORS te denken.

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

Afrondingssignaal

Het kleinste kanaal, voor als het resultaat zelf je niets aangaat: zet "Een afrondingssignaal versturen" aan en je pagina krijgt één bericht op het moment dat de speler klaar is.

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

Wat een resultaat bevat

Eén vorm, welk kanaal het ook draagt. De antwoorden van de speler zijn gesleuteld op de eigen item-id's van de activiteit, dus dezelfde sleutels komen terug in 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
}

De activiteit resetten vanaf jouw pagina

Eén instructie gaat de andere kant op. Met "Triggers van de bovenliggende pagina accepteren" aangezet kan de insluitende pagina de antwoorden van de speler wissen en de activiteit terugzetten naar het begin — voor een eigen "opnieuw proberen"-knop buiten het frame.

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

Je eigen spelersidentiteit meenemen

Als jouw platform al weet wie er speelt, hoeft de activiteit dat niet nog eens te vragen. Er zijn twee handshakes, allebei voor een activiteit binnen jouw pagina, en allebei door ons ingeschakeld in plaats van in de editor — ze bepalen aan wie een resultaat toebehoort, dus die stellen we samen met jou in plaats van via een vinkje.

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

Activiteiten maken vanuit jouw systeem

Alles hierboven gaat over een resultaat dat naar buiten komt. De andere kant op — de activiteiten zelf maken vanuit inhoud die je al hebt — is de Puzzle API: één POST per activiteitstype, en je krijgt een sleutel en een URL terug om in te sluiten.

Wanneer een kant-en-klare koppeling de betere oplossing is

Is het platform aan de andere kant een echt LMS, dan heb je dit allemaal waarschijnlijk niet nodig. Cijfers kunnen vanzelf terugkomen in de cijferlijst, zonder dat jij iets hoeft te hosten.

Wat er niet is

Zodat je er niet naar hoeft te zoeken:

• Geen endpoint om resultaten terug te lezen. De API maakt activiteiten aan; resultaten verlaten het systeem via de kanalen op deze pagina, of via de exports in je dashboard.
• Geen handtekening op de webhook. Er is niets om het verzoek tegen te verifiëren, en dat is waarom een resultaat niet het enige mag zijn dat iets belangrijks onderbouwt.
• Geen accountbrede webhook. De URL is een instelling op een activiteit, dus een activiteit die je kopieert neemt hem mee, en een nieuwe begint zonder.
• Niets bij een teamspel of een live room. Zowel de berichtkanalen als de webhook zijn voor solo spelen, en de instellingen schakelen zichzelf uit zodra teamspel aanstaat.
• Geen verzendwachtrij. Er wordt niets opgeslagen en opnieuw verstuurd — de volgende keer opslaan is de nieuwe poging, en de laatste aanroep van de run is degene die telt.