Kobl Puzzel til din egen platform

Hvilken kanal har du brug for?

Tre ting kan forlade en aktivitet, og én kan komme ind. Hvilken der passer, afhænger af ét spørgsmål: sidder spilleren inde i din side, eller et helt andet sted?

Resultatwebhook

Slå "Send resultater til en webhook" til i editoren, og giv den en URL. Fra da af sender spillerens browser hele resultatet som JSON med POST til den URL, hver gang deres fremskridt gemmes.

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

Resultater til siden omkring den

Hvis du indlejrer aktiviteten, kan du få den samme JSON sendt til din egen side i stedet for til en server. Slå "Send resultater til den overordnede side" til, og lyt efter beskeden. Intet forlader browseren, så der er intet endpoint at bygge og ingen CORS at tænke på.

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

Afslutningssignal

Den mindste kanal, til når selve resultatet ikke er din sag: slå "Send et afslutningssignal" til, og din side får én besked, i det øjeblik spilleren er færdig.

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

Hvad et resultat indeholder

Én form, uanset hvilken kanal der bærer den. Spillerens svar er nøglet efter aktivitetens egne item-id'er, så de samme nøgler dukker op i 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
}

Nulstil aktiviteten fra din side

Én instruktion rejser den anden vej. Med "Modtag triggere fra den overordnede side" slået til kan den side, der indlejrer, rydde spillerens svar og sætte aktiviteten tilbage til starten — til din egen "prøv igen"-knap uden for frame'n.

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

Medbring din egen spilleridentitet

Hvis din platform allerede ved, hvem der spiller, behøver aktiviteten ikke spørge igen. Der findes to håndtryk, begge til en aktivitet inde i din side, og begge slås til af os frem for i editoren — de ændrer, hvem et resultat hører til, så de sættes op sammen med dig frem for via et afkrydsningsfelt.

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

Opret aktiviteter fra dit eget system

Alt ovenfor handler om, at et resultat kommer ud. Den anden vej — at lave selve aktiviteterne ud fra indhold, du allerede har — er Puzzle API'et: ét POST-kald pr. aktivitetstype, og du får en nøgle og en URL til indlejring tilbage.

Når en færdig forbindelse er det bedre svar

Hvis platformen i den anden ende er et rigtigt LMS, har du sandsynligvis ikke brug for noget af dette. Karakterer kan gå tilbage til dets karakterbog af sig selv, uden at du skal hoste noget.

Hvad der ikke findes

Så du ikke går og leder efter det:

• Intet endpoint til at læse resultater tilbage. API'et opretter aktiviteter; resultater forlader systemet gennem kanalerne på denne side eller gennem eksporterne i dit dashboard.
• Ingen signatur på webhooken. Der er intet at verificere kaldet mod, og derfor bør et resultat ikke være det eneste, der står bag noget, der betyder noget.
• Ingen kontobred webhook. URL'en er en indstilling på en aktivitet, så en aktivitet, du kopierer, tager den med, og en ny starter uden den.
• Ingenting i et holdspil eller et live-rum. Både beskedkanalerne og webhooken er til solospil, og indstillingerne slår sig selv fra, når holdspil er slået til.
• Ingen leveringskø. Intet bliver gemt og sendt igen — den næste gemning er forsøget igen, og rundens sidste kald er det, der tæller.