Yhdistä Puzzel omaan alustaasi

Minkä kanavan tarvitset?

Kolme asiaa voi lähteä aktiviteetista ulos ja yksi voi tulla sisään. Kumpi sopii, riippuu yhdestä kysymyksestä: istuuko pelaaja sinun sivullasi vai jossain aivan muualla?

Tulosten webhook

Kytke editorissa päälle "Lähetä tulokset webhookiin" ja anna sille URL-osoite. Siitä lähtien pelaajan selain lähettää koko tuloksen POST-pyynnöllä kyseiseen osoitteeseen JSON-muodossa aina, kun pelaajan eteneminen tallennetaan.

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

Tulokset sen ympäröivälle sivulle

Jos upotat aktiviteetin, voit lähettää saman JSON:n omalle sivullesi palvelimen sijaan. Kytke päälle "Lähetä tulokset upottavalle sivulle" ja kuuntele viestiä. Mikään ei poistu selaimesta, joten päätepistettä ei tarvitse rakentaa eikä CORSia tarvitse miettiä.

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

Valmistumissignaali

Pienin kanava, kun itse tulos ei kuulu sinulle: kytke päälle "Lähetä valmistumissignaali", ja sivusi saa yhden viestin heti, kun pelaaja lopettaa.

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ä tulos sisältää

Yksi muoto, kanavasta riippumatta. Pelaajan vastausten avaimina toimivat aktiviteetin omat kohdetunnisteet, joten samat avaimet löytyvät myös kohteesta 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
}

Aktiviteetin nollaaminen sivultasi

Yksi komento kulkee toiseen suuntaan. Kun "Hyväksy komennot upottavalta sivulta" on kytketty päälle, upottava sivu voi tyhjentää pelaajan vastaukset ja palauttaa aktiviteetin alkuun — omaa "yritä uudelleen" -painiketta varten kehyksen ulkopuolella.

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

Oman pelaajaidentiteetin tuominen mukaan

Jos alustasi jo tietää, kuka pelaa, aktiviteetin ei tarvitse kysyä sitä uudelleen. Kaksi kättelyä on olemassa, molemmat sivullesi upotettua aktiviteettia varten, ja molemmat me kytkemme päälle emmekä sinä editorista — ne muuttavat sen, kenelle tulos kuuluu, joten ne otetaan käyttöön yhdessä kanssasi, ei valintaruudusta.

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

Aktiviteettien luominen omasta järjestelmästäsi

Kaikki edellä on tuloksesta, joka tulee ulos. Toiseen suuntaan — aktiviteettien tekeminen sisällöstä, joka sinulla jo on — on Puzzle API: yksi POST per aktiviteettityyppi, ja saat takaisin avaimen ja upotettavan URL-osoitteen.

Kun valmis liitäntä on parempi vastaus

Jos toisella puolella on oikea LMS, et todennäköisesti tarvitse mitään tästä. Arvosanat voivat palautua sen arvosanataulukkoon itsestään, eikä sinun tarvitse isännöidä mitään.

Mitä ei ole

Ettet turhaan etsi näitä:

• Ei päätepistettä tulosten lukemiseen takaisin. API luo aktiviteetteja; tulokset lähtevät tämän sivun kanavien kautta tai hallintapaneelisi vientien kautta.
• Ei allekirjoitusta webhookissa. Ei ole mitään, mitä vasten pyyntö voisi tarkistaa, minkä vuoksi tuloksen ei pitäisi olla ainoa asia, joka kannattelee jotain tärkeää.
• Ei tilinlaajuista webhookia. URL-osoite on aktiviteettikohtainen asetus, joten kopioimasi aktiviteetti kuljettaa sen mukanaan, ja uusi aktiviteetti aloittaa ilman sitä.
• Ei mitään joukkuepelissä tai livehuoneessa. Molemmat viestikanavat ja webhook on tarkoitettu yksinpeliin, ja asetukset kytkeytyvät itse pois päältä, kun moninpeli on käytössä.
• Ei toimitusjonoa. Mitään ei tallenneta ja lähetetä uudelleen — seuraava tallennus on uusintayritys, ja pelikerran viimeinen kutsu on se, joka ratkaisee.