Poveži Puzzel s svojo platformo

Kateri kanal potrebuješ?

Iz dejavnosti lahko odidejo tri stvari, ena pa lahko pride noter. Kateri kanal ustreza, je odvisno od enega samega vprašanja: ali igralec sedi znotraj tvoje strani ali povsem drugje?

Webhook za rezultate

V urejevalniku vklopi "Pošlji rezultate na webhook" in vnesi URL. Od takrat naprej brskalnik igralca ob vsakem shranjevanju napredka pošlje cel rezultat na ta URL z metodo POST, kot 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);
});

Rezultati na nadrejeno stran

Če dejavnost vdelaš, lahko isti JSON pošlješ svoji strani namesto strežniku. Vklopi "Pošlji rezultate na nadrejeno stran" in poslušaj sporočilo. Iz brskalnika ne gre nič, zato ni treba zgraditi končne točke ali razmišljati o 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>

Signal o zaključku

Najmanjši kanal, za primere, ko te sam rezultat ne zanima: vklopi "Pošlji signal o zaključku" in tvoja stran ob trenutku, ko igralec konča, prejme eno sporočilo.

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

Kaj vsebuje rezultat

Ena oblika, ne glede na to, kateri kanal jo prenaša. Igralčevi odgovori so ključeni po id-jih elementov same dejavnosti, zato se enaki ključi pojavijo tudi 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
}

Ponastavitev dejavnosti s tvoje strani

En ukaz potuje v drugo smer. Ko je vklopljeno "Sprejmi sprožilce z nadrejene strani", lahko stran, ki dejavnost vdeluje, počisti igralčeve odgovore in dejavnost vrne na začetek — za tvoj lasten gumb "poskusi znova" zunaj okvirja.

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

Prinesi svojo identiteto igralca

Če tvoja platforma že ve, kdo igra, dejavnosti ni treba spet vprašati. Obstajata dve rokovanji, obe za dejavnost znotraj tvoje strani, in obe vklopimo mi, ne ti v urejevalniku — spremenita namreč, komu rezultat pripada, zato ju nastavimo skupaj s tabo, ne prek potrditvenega polja.

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

Ustvarjanje dejavnosti iz tvojega sistema

Vse zgoraj govori o tem, kako rezultat pride ven. Obratna smer — ustvarjanje samih dejavnosti iz vsebine, ki jo že imaš — je Puzzle API: en POST na vrsto dejavnosti, nazaj pa dobiš ključ in URL za vdelavo.

Kadar je pripravljen povezovalnik boljša izbira

Če je platforma na drugi strani pravi LMS, verjetno ne potrebuješ ničesar od tega. Ocene se lahko same vrnejo v njegovo redovalnico, ne da bi ti moral karkoli gostiti.

Česa ni

Da tega ne iščeš zaman:

• Ni končne točke za branje rezultatov nazaj. API ustvarja dejavnosti; rezultati odhajajo skozi kanale na tej strani ali skozi izvoze v tvoji nadzorni plošči.
• Webhook ni podpisan. Ni ničesar, s čimer bi zahtevo preveril, zato rezultat ne sme biti edina stvar, na kateri temelji nekaj pomembnega.
• Ni webhooka za cel račun. URL je nastavitev posamezne dejavnosti, zato ga kopirana dejavnost prevzame, nova pa se začne brez njega.
• Nič pri ekipni igri ali sobi v živo. Oba sporočilna kanala in webhook so namenjeni samostojnemu igranju, nastavitve pa se same izklopijo, ko je vklopljena ekipna igra.
• Ni čakalne vrste za dostavo. Nič se ne shrani in ponovno pošlje — naslednje shranjevanje je ponovni poskus, pomemben pa je zadnji klic poskusa.