Koble Puzzel til din egen plattform

Hvilken kanal trenger du?

Tre ting kan forlate en aktivitet, og én kan komme inn. Hvilken som passer, avhenger av ett enkelt spørsmål: sitter spilleren inne på din side, eller et helt annet sted?

Resultat-webhook

Slå på "Send resultater til en webhook" i editoren og oppgi en URL. Fra da av sender spillerens nettleser hele resultatet som JSON med POST til den URL-en, hver gang fremgangen lagres.

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 rundt

Hvis du bygger inn aktiviteten, kan du få den samme JSON-en sendt til din egen side i stedet for til en server. Slå på "Send resultater til den overordnede siden" og lytt etter meldingen. Ingenting forlater nettleseren, så det er ikke noe endepunkt å bygge og ingen CORS å tenke 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>

Fullføringssignal

Den minste kanalen, for når selve resultatet ikke er din sak: slå på "Send et fullføringssignal" og siden din får én melding i det øyeblikket spilleren er ferdig.

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

Hva et resultat inneholder

Én form, uansett hvilken kanal som bærer den. Spillerens svar er nøkkelbasert på aktivitetens egne element-id-er, så de samme nøklene dukker opp 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
}

Tilbakestille aktiviteten fra siden din

Én instruks går den andre veien. Med "Godta utløsere fra den overordnede siden" slått på kan siden som bygger inn aktiviteten tømme spillerens svar og sette aktiviteten tilbake til start — for din egen "prøv igjen"-knapp utenfor rammen.

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

Ta med din egen spilleridentitet

Hvis plattformen din allerede vet hvem som spiller, trenger ikke aktiviteten å spørre igjen. Det finnes to håndtrykk, begge for en aktivitet inne på siden din, og begge slås på av oss i stedet for i editoren — de endrer hvem et resultat tilhører, så de settes opp sammen med deg i stedet for fra en avkryssingsboks.

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

Opprette aktiviteter fra systemet ditt

Alt over handler om at et resultat kommer ut. Å gå den andre veien — å lage selve aktivitetene fra innhold du allerede har — er Puzzle API-et: én POST per aktivitetstype, og du får tilbake en nøkkel og en URL å bygge inn.

Når en ferdig kobling er det bedre svaret

Hvis plattformen på den andre siden er en ekte LMS, trenger du sannsynligvis ikke noe av dette. Karakterer kan gå tilbake til karakterboken av seg selv, uten at du trenger å drifte noe.

Hva som ikke finnes

Så du slipper å lete etter det:

• Ingen endepunkt for å lese resultater tilbake. API-et oppretter aktiviteter; resultater forlater gjennom kanalene på denne siden, eller gjennom eksportene i dashbordet ditt.
• Ingen signatur på webhooken. Det finnes ingenting å verifisere forespørselen mot, og det er derfor et resultat ikke bør være det eneste som står bak noe som betyr noe.
• Ingen kontoomfattende webhook. URL-en er en innstilling på en aktivitet, så en aktivitet du kopierer tar den med seg, mens en ny starter uten den.
• Ingenting i et lagspill eller et direkterom. Begge meldingskanalene og webhooken er for solospill, og innstillingene slår seg selv av når lagspill er på.
• Ingen leveringskø. Ingenting lagres og sendes på nytt — neste lagring er forsøket på nytt, og rundens siste kall er det som teller.