Podłącz Puzzel do własnej platformy

Którego kanału potrzebujesz?

Z aktywności mogą wyjść trzy rzeczy, a jedna może do niej wejść. To, która pasuje, zależy od jednego pytania: czy gracz znajduje się wewnątrz twojej strony, czy zupełnie gdzie indziej?

Webhook wyników

Włącz ustawienie "Wysyłaj wyniki do webhooka" w edytorze i podaj adres URL. Od tej pory za każdym razem, gdy postęp gracza zostanie zapisany, jego przeglądarka wyśle metodą POST cały wynik na ten adres jako 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);
});

Wyniki do strony osadzającej

Jeśli osadzasz aktywność, możesz sprawić, że ten sam JSON trafi na twoją własną stronę zamiast na serwer. Włącz "Wysyłaj wyniki do strony nadrzędnej" i nasłuchuj wiadomości. Nic nie opuszcza przeglądarki, więc nie musisz budować żadnego endpointu ani martwić się 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>

Sygnał ukończenia

Najmniejszy kanał, na wypadek gdy sam wynik cię nie interesuje: włącz "Wysyłaj sygnał ukończenia", a twoja strona dostanie jedną wiadomość w chwili, gdy gracz skończy.

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

Co zawiera wynik

Jeden kształt danych, niezależnie od tego, który kanał je niesie. Odpowiedzi gracza są indeksowane identyfikatorami elementów samej aktywności, więc te same klucze pojawiają się w 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
}

Resetowanie aktywności z twojej strony

Jedna instrukcja podróżuje w drugą stronę. Gdy włączysz "Przyjmuj polecenia ze strony nadrzędnej", strona osadzająca może wyczyścić odpowiedzi gracza i cofnąć aktywność do początku — na potrzeby własnego przycisku "spróbuj ponownie" poza ramką.

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

Wykorzystanie własnej tożsamości gracza

Jeśli twoja platforma już wie, kto gra, aktywność nie musi pytać o to ponownie. Istnieją dwa uzgodnienia, oba dla aktywności osadzonej na twojej stronie, i oba włączane przez nas, a nie w edytorze — zmieniają one, do kogo należy wynik, więc ustawiamy je razem z tobą, a nie za pomocą zwykłego przełącznika.

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

Tworzenie aktywności z twojego systemu

Wszystko powyżej dotyczy wyniku, który wychodzi na zewnątrz. W drugą stronę — tworzenie samych aktywności z treści, które już masz — służy do tego Puzzle API: jedno zapytanie POST na typ aktywności, w zamian dostajesz klucz i adres URL do osadzenia.

Kiedy gotowa integracja jest lepszym rozwiązaniem

Jeśli platforma po drugiej stronie to prawdziwy LMS, prawdopodobnie nic z tego nie jest ci potrzebne. Oceny mogą trafiać do jego dziennika ocen same, bez niczego, co musiałbyś hostować.

Czego tu nie ma

Żebyś nie szukał tego na próżno:

• Brak endpointu do odczytu wyników z powrotem. API tworzy aktywności; wyniki wychodzą przez kanały opisane na tej stronie albo przez eksporty w twoim panelu.
• Brak podpisu na webhooku. Nie ma niczego, względem czego można zweryfikować zapytanie, dlatego wynik nie powinien być jedyną rzeczą stojącą za czymś, na czym naprawdę zależy.
• Brak webhooka na poziomie całego konta. Adres URL jest ustawieniem pojedynczej aktywności, więc skopiowana aktywność przenosi go ze sobą, a nowa zaczyna bez niego.
• Nic w grze drużynowej ani w pokoju na żywo. Oba kanały wiadomości i webhook są przeznaczone do gry solo, a ustawienia same się wyłączają, gdy włączony jest tryb drużynowy.
• Brak kolejki dostarczania. Nic nie jest przechowywane i wysyłane ponownie — kolejny zapis pełni rolę ponowienia, a liczy się tylko ostatnie wywołanie danego przebiegu.