Tengdu Puzzel við þitt eigið kerfi

Hvaða leið hentar þér?

Þrennt getur farið út úr verkefni og eitt getur komið inn. Hvað hentar þér fer eftir einni spurningu: situr leikmaðurinn inni í síðunni þinni, eða einhvers staðar allt annars staðar?

Webhook fyrir niðurstöður

Kveiktu á "Senda niðurstöður á webhook" í ritlinum og gefðu upp vefslóð. Upp frá því sendir vafri leikmannsins alla niðurstöðuna sem JSON með POST á þá vefslóð, í hvert sinn sem framvindan er vistuð.

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

Niðurstöður á yfirsíðuna

Ef þú fellir verkefnið inn geturðu fengið sama JSON-ið sent á þína eigin síðu í stað vefþjóns. Kveiktu á "Senda niðurstöður á yfirsíðuna" og hlustaðu eftir skilaboðunum. Ekkert fer út úr vafranum, svo það þarf hvorki að smíða endapunkt né hugsa um 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>

Lokamerki

Minnsta leiðin, fyrir þegar niðurstaðan sjálf kemur þér ekkert við: kveiktu á "Senda lokamerki" og síðan þín fær ein skilaboð um leið og leikmaðurinn lýkur verkefninu.

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

Hvað niðurstaða inniheldur

Eitt snið, sama hvaða leið ber það. Svör leikmannsins eru lykluð með auðkennum verkefnisins sjálfs, svo sömu lyklarnir koma fram í 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
}

Að endurstilla verkefnið frá síðunni þinni

Ein skipun ferðast í hina áttina. Þegar kveikt er á "Taka við skipunum frá yfirsíðunni" getur síðan sem fellir verkefnið inn hreinsað svör leikmannsins og sett verkefnið aftur á byrjunarreit — fyrir þinn eigin "reyna aftur" hnapp, fyrir utan rammann.

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

Að nota þitt eigið auðkenni leikmanna

Ef kerfið þitt veit nú þegar hver er að spila þarf verkefnið ekki að spyrja um það aftur. Tvö handabönd eru í boði, bæði fyrir verkefni inni í síðunni þinni, og bæði virkjuð af okkur frekar en í ritlinum — þau breyta því hverjum niðurstaða tilheyrir, svo þau eru sett upp í samráði við þig frekar en með hökmerki.

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

Að búa til verkefni úr kerfinu þínu

Allt hér að ofan snýst um niðurstöðu sem kemur út. Í hina áttina — að búa til verkefnin sjálf úr efni sem þú átt nú þegar — er Puzzle API: ein POST-fyrirspurn fyrir hverja tegund verkefnis, og þú færð til baka lykil og vefslóð til að fella inn.

Þegar tilbúin tenging er betri kostur

Ef kerfið hinum megin er alvöru LMS þarftu líklega ekkert af þessu. Einkunnir geta borist sjálfkrafa í einkunnabókina þess, án þess að þú þurfir að hýsa neitt.

Hvað er ekki í boði

Svo þú eyðir ekki tíma í að leita að því:

• Enginn endapunktur til að lesa niðurstöður til baka. API-ið býr til verkefni; niðurstöður fara út um leiðirnar á þessari síðu, eða um útflutninginn í stjórnborðinu þínu.
• Engin undirskrift á webhook-inu. Það er ekkert til að sannreyna fyrirspurnina gegn, sem er ástæðan fyrir því að niðurstaða ætti ekki að vera það eina sem stendur á bak við eitthvað sem skiptir máli.
• Ekkert webhook fyrir allan aðganginn. Vefslóðin er stilling á verkefni, svo verkefni sem þú afritar ber hana með sér og nýtt verkefni byrjar án hennar.
• Ekkert í liðaleik eða beinni lotu. Bæði skilaboðaleiðirnar og webhook-ið eru fyrir einstaklingsspilun, og stillingarnar slökkva sjálfkrafa á sér þegar liðaspilun er virk.
• Engin biðröð fyrir sendingar. Ekkert er geymt og sent aftur — næsta vistun er endurtilraunin, og síðasta kall keyrslunnar er það sem skiptir máli.