Prepoj Puzzel s vlastnou platformou

Ktorý kanál potrebuješ?

Z aktivity môžu odísť tri veci a jedna môže prísť dovnútra. Ktorá sa hodí, závisí od jedinej otázky: sedí hráč priamo na tvojej stránke, alebo úplne inde?

Webhook na výsledky

Zapni "Posielať výsledky na webhook" v editore a zadaj URL adresu. Odvtedy pri každom uložení hráčovho postupu jeho prehliadač odošle celý výsledok na túto adresu metódou POST vo formáte 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);
});

Výsledky stránke okolo nej

Ak aktivitu vkladáš, môžeš mať ten istý JSON odoslaný vlastnej stránke namiesto serveru. Zapni "Posielať výsledky nadradenej stránke" a počúvaj správu. Z prehliadača nič neodchádza, takže nemusíš stavať žiadny endpoint ani riešiť 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í

Najmenší kanál, pre prípad, že samotný výsledok nie je tvoja vec: zapni "Odoslať signál o dokončení" a tvoja stránka dostane jednu správu vo chvíli, keď 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"
}

Čo obsahuje výsledok

Jeden tvar, nech ho prenáša akýkoľvek kanál. Hráčove odpovede sú indexované podľa vlastných id položiek aktivity, takže rovnaké kľúče sa objavia aj 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
}

Reštartovanie aktivity z tvojej stránky

Jeden pokyn ide opačným smerom. Keď je zapnuté "Prijímať príkazy z nadradenej stránky", stránka, ktorá aktivitu vkladá, môže vymazať hráčove odpovede a vrátiť aktivitu na začiatok — pre vlastné tlačidlo "skúsiť znova" mimo rámca.

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áča

Ak tvoja platforma už vie, kto hrá, aktivita sa ho nemusí znova pýtať. Existujú dva postupy, oba pre aktivitu na tvojej stránke, a oba zapíname my, nie ty v editore — menia, komu výsledok patrí, takže sa nastavujú spoločne s nami, nie 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áranie aktivít z tvojho systému

Všetko vyššie sa týka výsledku, ktorý odchádza. Opačný smer — vytváranie samotných aktivít z obsahu, ktorý už máš — je Puzzle API: jeden POST na typ aktivity, a späť dostaneš kľúč a URL adresu na vloženie.

Keď je lepšou odpoveďou hotový konektor

Ak je platforma na druhej strane skutočný LMS, väčšinou nič z tohto nepotrebuješ. Známky sa dokážu samy vrátiť do jeho triednej klasifikácie, bez toho, aby si čokoľvek hostoval.

Čo tu nie je

Aby si to nehľadal zbytočne:

• Žiadny endpoint na spätné čítanie výsledkov. API vytvára aktivity; výsledky odchádzajú cez kanály na tejto stránke alebo cez exporty v tvojom prehľade.
• Žiadny podpis na webhooku. Nie je voči čomu požiadavku overiť, a preto by výsledok nemal byť jedinou oporou niečoho, na čom záleží.
• Žiadny webhook platný pre celý účet. URL adresa je nastavenie jednotlivej aktivity, takže skopírovaná aktivita si ho nesie so sebou a nová ho na začiatku nemá.
• Nič v tímovej hre ani v živej miestnosti. Oba kanály so správami aj webhook sú určené na hru jednotlivca a nastavenia sa samy vypnú, keď je zapnutá tímová hra.
• Žiadny front na doručovanie. Nič sa neukladá a neposiela znova — ďalšie uloženie je ten opakovaný pokus a rozhoduje posledné volanie behu.