Napoj Puzzel na vlastní platformu

Který kanál potřebuješ?

Z aktivity můžou odejít tři věci a jedna může přijít dovnitř. Který kanál sedí, záleží na jediné otázce: sedí hráč přímo na tvojí stránce, nebo úplně jinde?

Webhook s výsledky

V editoru zapni "Odesílat výsledky na webhook" a zadej URL. Od té chvíle při každém uložení hráčova postupu odešle jeho prohlížeč metodou POST celý výsledek jako JSON na tuhle adresu.

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

Výsledky stránce kolem ní

Když aktivitu vkládáš, můžeš nechat stejný JSON odeslat vlastní stránce místo na server. Zapni "Odesílat výsledky nadřazené stránce" a naslouchej zprávě. Z prohlížeče nic neodchází, takže nemusíš stavět žádný koncový bod ani řešit CORS.

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

Signál o dokončení

Nejmenší kanál, pro chvíle, kdy ti do samotného výsledku nic není: zapni "Odeslat signál o dokončení" a tvoje stránka dostane jednu zprávu ve chvíli, kdy hráč skončí.

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

Co obsahuje výsledek

Jeden tvar, ať ho nese jakýkoli kanál. Hráčovy odpovědi jsou klíčované id položek dané aktivity, takže stejné klíče se objeví i v 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
}

Reset aktivity z tvojí stránky

Jedním směrem jde příkaz opačně. Když je zapnuté "Přijímat příkazy z nadřazené stránky", stránka, která aktivitu vkládá, může smazat hráčovy odpovědi a vrátit aktivitu na začátek — pro vlastní tlačítko "zkusit znovu" mimo rámec.

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

Vlastní identita hráče

Pokud tvoje platforma už ví, kdo hraje, aktivita se ho nemusí ptát znovu. Existují dva způsoby handshaku, oba pro aktivitu uvnitř tvojí stránky, a oba zapínáme my, ne editor — mění totiž, komu výsledek patří, takže se nastavují s námi, ne zaškrtnutím políčka.

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

Vytváření aktivit z tvého systému

Všechno výše se týkalo výsledku, který jde ven. Opačným směrem — vytvoření samotných aktivit z obsahu, který už máš — slouží Puzzle API: jeden POST na typ aktivity, a zpátky dostaneš klíč a URL pro vložení.

Kdy je lepší odpovědí hotový konektor

Pokud je na druhé straně skutečný LMS, nic z tohohle asi nepotřebuješ. Známky se do jeho třídní knihy dostanou samy, aniž bys musel cokoli hostovat.

Co tu není

Ať to zbytečně nehledáš:

• Žádný koncový bod pro čtení výsledků zpátky. API aktivity vytváří; výsledky odcházejí přes kanály na téhle stránce nebo přes exporty ve tvojí nástěnce.
• Webhook nemá žádný podpis. Není proti čemu požadavek ověřit, a proto by výsledek neměl být jediné, co stojí za něčím důležitým.
• Žádný webhook platný pro celý účet. URL je nastavení jednotlivé aktivity, takže zkopírovaná aktivita si ho ponese s sebou a nová začíná bez něj.
• Nic v týmové hře ani v živé místnosti. Oba zprávové kanály i webhook jsou pro hru jednoho hráče a nastavení se samy vypnou, jakmile je zapnutá týmová hra.
• Žádná fronta pro doručování. Nic se neukládá a znovu neposílá — dalším pokusem je další uložení a záleží jen na posledním volání běhu.