Puzzel in deine eigene Plattform einbinden

Welchen Kanal brauchst du?

Drei Dinge können eine Aktivität verlassen, eines kann hineinkommen. Was passt, hängt von einer einzigen Frage ab: Sitzt der Spieler auf deiner eigenen Seite oder ganz woanders?

Ergebnis-Webhook

Aktivier "Ergebnisse an einen Webhook senden" im Editor und gib eine URL an. Von da an sendet der Browser des Spielers bei jedem Speichern des Fortschritts das komplette Ergebnis als JSON per POST an diese 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);
});

Ergebnisse an die umgebende Seite

Wenn du die Aktivität einbettest, kannst du dasselbe JSON an deine eigene Seite senden lassen statt an einen Server. Aktivier "Ergebnisse an die übergeordnete Seite senden" und lausche auf die Nachricht. Nichts verlässt den Browser, also musst du keinen Endpunkt bauen und dir keine Gedanken über CORS machen.

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

Abschlusssignal

Der kleinste Kanal, für den Fall, dass dich das Ergebnis selbst nichts angeht: Aktivier "Abschlusssignal senden" und deine Seite bekommt eine Nachricht in dem Moment, in dem der Spieler fertig ist.

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

Was ein Ergebnis enthält

Eine Form, egal welcher Kanal sie trägt. Die Antworten des Spielers sind nach den eigenen Element-IDs der Aktivität geschlüsselt, sodass dieselben Schlüssel auch in correctUids auftauchen.

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

Die Aktivität von deiner Seite aus zurücksetzen

Eine Anweisung geht den umgekehrten Weg. Ist "Auslöser von der übergeordneten Seite annehmen" aktiviert, kann die einbettende Seite die Antworten des Spielers löschen und die Aktivität auf den Anfang zurücksetzen — für eine eigene "Nochmal versuchen"-Schaltfläche außerhalb des Frames.

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

Deine eigene Spieleridentität mitbringen

Wenn deine Plattform schon weiß, wer spielt, muss die Aktivität nicht noch einmal danach fragen. Es gibt zwei Handshakes, beide für eine Aktivität innerhalb deiner Seite, und beide werden von uns aktiviert statt im Editor — sie ändern, wem ein Ergebnis zugeordnet wird, deshalb werden sie gemeinsam mit dir eingerichtet und nicht über eine Checkbox.

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

Aktivitäten aus deinem eigenen System erstellen

Alles oben dreht sich darum, dass ein Ergebnis rauskommt. Der umgekehrte Weg — die Aktivitäten selbst aus Inhalten zu erstellen, die du schon hast — ist die Puzzle-API: ein POST pro Aktivitätstyp, und du bekommst einen Schlüssel und eine URL zum Einbetten zurück.

Wenn ein fertiger Connector die bessere Antwort ist

Wenn die Plattform auf der anderen Seite ein echtes LMS ist, brauchst du wahrscheinlich nichts von alldem. Noten können von allein ins Notenbuch zurückfließen, ohne dass du etwas hosten musst.

Was es nicht gibt

Damit du nicht danach suchst:

• Kein Endpunkt zum Auslesen von Ergebnissen. Die API erstellt Aktivitäten; Ergebnisse verlassen das System über die Kanäle auf dieser Seite oder über die Exporte in deinem Dashboard.
• Keine Signatur beim Webhook. Es gibt nichts, wogegen du die Anfrage prüfen könntest — deshalb sollte ein Ergebnis nie das Einzige sein, was hinter etwas Wichtigem steht.
• Kein kontoweiter Webhook. Die URL ist eine Einstellung an einer Aktivität — eine kopierte Aktivität übernimmt sie, eine neue startet ohne sie.
• Nichts bei einem Team-Spiel oder einem Live-Raum. Beide Nachrichtenkanäle und der Webhook sind für Einzelspiel gedacht, und die Einstellungen schalten sich selbst aus, sobald der Team-Modus aktiv ist.
• Keine Zustellwarteschlange. Nichts wird gespeichert und erneut gesendet — das nächste Speichern ist der Wiederholungsversuch, und der letzte Aufruf des Durchlaufs zählt.