Kösd össze a Puzzelt a saját platformoddal

Melyik csatornára van szükséged?

Három dolog hagyhatja el a tevékenységet, és egy jöhet be. Hogy melyik illik hozzád, egyetlen kérdésen múlik: a játékos a te oldaladon belül ül, vagy egészen máshol?

Eredmény-webhook

Kapcsold be a szerkesztőben az „Eredmények küldése webhookra” beállítást, és add meg hozzá egy URL-t. Ettől kezdve minden alkalommal, amikor a játékos haladása mentésre kerül, a böngészője POST kéréssel elküldi a teljes eredményt JSON-ként arra az URL-re.

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

Eredmények a beágyazó oldalnak

Ha beágyazod a tevékenységet, ugyanezt a JSON-t elküldheted a saját oldaladnak egy szerver helyett. Kapcsold be az „Eredmények küldése a szülőoldalnak” beállítást, és figyeld az üzenetet. Semmi nem hagyja el a böngészőt, így nincs végpont, amit fel kellene építened, és nincs CORS, amivel foglalkoznod kellene.

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

Befejezésjelzés

A legkisebb csatorna, arra az esetre, ha maga az eredmény nem tartozik rád: kapcsold be a „Befejezésjelzés küldése” beállítást, és az oldalad egyetlen üzenetet kap abban a pillanatban, amikor a játékos befejezi.

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

Mit tartalmaz egy eredmény

Egyetlen forma, akármelyik csatorna hordozza is. A játékos válaszainak kulcsa a tevékenység saját elem-azonosítója, ezért ugyanezek a kulcsok jelennek meg a correctUids mezőben is.

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

A tevékenység visszaállítása az oldaladról

Egy utasítás a másik irányba is utazik. Ha bekapcsolod a „Vezérlés fogadása a szülőoldalról” beállítást, a beágyazó oldal törölheti a játékos válaszait, és visszaállíthatja a tevékenységet a kezdetére — egy saját „próbáld újra” gombhoz, a kereten kívül.

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

Hozd magaddal a játékos azonosítását

Ha a platformod már tudja, ki játszik, a tevékenységnek nem kell újra megkérdeznie. Két kézfogás létezik erre, mindkettő egy, az oldaladba ágyazott tevékenységhez, és mindkettőt mi kapcsoljuk be, nem a szerkesztőben — mivel megváltoztatják, kihez tartozik egy eredmény, ezeket veled egyeztetve állítjuk be, nem egy jelölőnégyzettel.

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

Tevékenységek létrehozása a saját rendszeredből

Minden fent leírt dolog egy kimenő eredményről szól. A másik irány — maguknak a tevékenységeknek a létrehozása egy már meglévő tartalomból — a Puzzle API dolga: egy POST kérés tevékenységtípusonként, cserébe egy kulcsot és egy beágyazható URL-t kapsz.

Amikor egy kész összekötő a jobb válasz

Ha a másik oldalon egy valódi LMS áll, valószínűleg semmi erre nincs szükséged. Az osztályzatok maguktól visszakerülhetnek az osztálynaplójába, anélkül hogy neked bármit is üzemeltetned kellene.

Amit nem találsz itt

Hogy ne is keresd hiába:

• Nincs végpont az eredmények visszaolvasására. Az API tevékenységeket hoz létre; az eredmények az ezen az oldalon szereplő csatornákon keresztül, vagy az irányítópultod exportjain keresztül hagyják el a rendszert.
• Nincs aláírás a webhookon. Nincs mihez viszonyítva ellenőrizni a kérést, ezért egy eredmény nem lehet az egyetlen alapja valaminek, ami valóban számít.
• Nincs fiókszintű webhook. Az URL egy tevékenység beállítása, ezért egy lemásolt tevékenység magával viszi, egy új pedig nélküle indul.
• Semmi nincs egy csapatjátékban vagy egy élő szobában. Mindkét üzenetcsatorna és a webhook is egyjátékos játékra való, és a beállítások automatikusan kikapcsolnak, amikor a csapatjáték be van kapcsolva.
• Nincs kézbesítési sor. Semmi nem tárolódik és küldődik újra — a következő mentés maga az újrapróbálkozás, és a menet utolsó hívása számít.