Koppla samman Puzzel med din egen plattform

Vilken kanal behöver du?

Tre saker kan lämna en aktivitet och en kan komma in. Vilken som passar avgörs av en enda fråga: sitter spelaren inne i din sida, eller någon helt annanstans?

Resultatwebhook

Slå på "Skicka resultat till en webhook" i redigeraren och ange en URL. Från och med då POSTar spelarens webbläsare hela resultatet som JSON till den URL:en varje gång deras framsteg sparas.

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

Resultat till sidan runt om

Om du bäddar in aktiviteten kan du få samma JSON skickad till din egen sida istället för till en server. Slå på "Skicka resultat till den överordnade sidan" och lyssna efter meddelandet. Inget lämnar webbläsaren, så det finns ingen slutpunkt att bygga och ingen CORS att tänka 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>

Klarsignal

Den minsta kanalen, för när själva resultatet inte är din sak: slå på "Skicka en klarsignal" så får din sida ett meddelande i samma stund som spelaren blir klar.

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

Vad ett resultat innehåller

En och samma form, oavsett vilken kanal som bär den. Spelarens svar är nyckelsatta med aktivitetens egna objekt-id:n, så samma nycklar dyker upp 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
}

Nollställa aktiviteten från din sida

En instruktion går åt andra hållet. Med "Ta emot kommandon från den överordnade sidan" påslagen kan sidan som gör inbäddningen rensa spelarens svar och sätta tillbaka aktiviteten till starten — för en egen knapp för "försök igen" utanför ramen.

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 spelaridentitet

Om din plattform redan vet vem som spelar behöver aktiviteten inte fråga igen. Det finns två handskakningar, båda för en aktivitet inne i din sida, och båda slås på av oss istället för i redigeraren — de ändrar vem ett resultat tillhör, så de ställs in tillsammans med dig istället för via en kryssruta.

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

Skapa aktiviteter från ditt system

Allt ovanför handlar om att ett resultat kommer ut. Att göra tvärtom — skapa själva aktiviteterna från innehåll du redan har — är Puzzle API:et: en POST per aktivitetstyp, och du får tillbaka en nyckel och en URL att bädda in.

När en färdig koppling är det bättre svaret

Om plattformen på andra sidan är ett riktigt LMS behöver du förmodligen inget av det här. Betyg kan gå tillbaka till dess betygsbok av sig själva, utan att du behöver driva något själv.

Vad som inte finns

Så att du inte letar efter det:

• Ingen slutpunkt för att läsa tillbaka resultat. API:et skapar aktiviteter; resultat lämnar genom kanalerna på den här sidan, eller genom exporterna i din instrumentpanel.
• Ingen signatur på webhooken. Det finns inget att verifiera förfrågan mot, vilket är varför ett resultat inte bör vara det enda som står bakom något som är viktigt.
• Ingen kontoomfattande webhook. URL:en är en inställning på en aktivitet, så en aktivitet du kopierar för med sig den, och en ny börjar utan den.
• Inget i ett lagspel eller ett live-rum. Både meddelandekanalerna och webhooken är till för spel på egen hand, och inställningarna stänger av sig själva när lagspel är påslaget.
• Ingen leveranskö. Inget lagras och skickas om — nästa sparning är omförsöket, och omgångens sista anrop är det som räknas.