Conectează Puzzel la propria ta platformă

De care canal ai nevoie?

Trei lucruri pot ieși dintr-o activitate și unul poate intra. Care ți se potrivește depinde de o singură întrebare: jucătorul stă în pagina ta sau cu totul altundeva?

Webhook pentru rezultate

Activează „Trimite rezultatele către un webhook” în editor și dă-i un URL. Din acel moment, de fiecare dată când progresul jucătorului este salvat, browserul lui trimite (POST) întregul rezultat către acel URL, ca JSON.

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

Rezultate către pagina din jur

Dacă încorporezi activitatea, poți primi același JSON trimis către propria pagină în loc de către un server. Activează „Trimite rezultatele către pagina părinte” și ascultă mesajul. Nimic nu iese din browser, așa că nu ai niciun endpoint de construit și niciun CORS la care să te gândești.

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

Semnal de finalizare

Cel mai mic canal, pentru când rezultatul în sine nu te privește: activează „Trimite un semnal de finalizare”, iar pagina ta primește un singur mesaj în clipa în care jucătorul termină.

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

Ce conține un rezultat

O singură formă, indiferent de canalul care o poartă. Răspunsurile jucătorului sunt indexate după id-urile proprii ale elementelor activității, așa că aceleași chei apar și în 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
}

Resetarea activității din pagina ta

O singură instrucțiune circulă în celălalt sens. Cu „Acceptă comenzi de la pagina părinte” activat, pagina care face încorporarea poate șterge răspunsurile jucătorului și poate readuce activitatea la început — pentru propriul tău buton „încearcă din nou”, din afara cadrului.

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

Aducerea propriei identități de jucător

Dacă platforma ta știe deja cine joacă, activitatea nu mai trebuie să întrebe din nou. Există două tipuri de handshake, ambele pentru o activitate din interiorul paginii tale, și ambele activate de noi, nu din editor — schimbă cui îi aparține un rezultat, așa că se configurează împreună cu tine, nu dintr-o casetă de bifat.

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

Crearea activităților din sistemul tău

Tot ce e mai sus se referă la un rezultat care iese. În celălalt sens — crearea activităților în sine din conținut pe care îl ai deja — este Puzzle API: un POST pentru fiecare tip de activitate, iar tu primești înapoi o cheie și un URL de încorporat.

Când un conector gata făcut e răspunsul mai bun

Dacă platforma de cealaltă parte este un LMS adevărat, probabil nu ai nevoie de nimic din toate acestea. Notele pot ajunge singure în carnetul lui de note, fără nimic de găzduit din partea ta.

Ce nu există

Ca să nu îl cauți degeaba:

• Niciun endpoint pentru citirea rezultatelor înapoi. API-ul creează activități; rezultatele ies prin canalele de pe această pagină, sau prin exporturile din tabloul tău de bord.
• Nicio semnătură pe webhook. Nu există nimic în raport cu care să verifici cererea, motiv pentru care un rezultat nu ar trebui să fie singurul lucru din spatele a ceva ce contează.
• Niciun webhook la nivel de cont. URL-ul este o setare pe o activitate, așa că o activitate pe care o copiezi îl duce cu ea, iar una nouă pornește fără el.
• Nimic într-un joc pe echipe sau într-o cameră live. Ambele canale de mesaje și webhook-ul sunt pentru joc solo, iar setările se dezactivează singure când modul pe echipe este activ.
• Nicio coadă de livrare. Nimic nu este stocat și retrimis — următoarea salvare este reîncercarea, iar ultimul apel al rundei este cel care contează.