Hubungkan Puzzel ke platformmu sendiri

Saluran mana yang kamu butuhkan?

Ada tiga hal yang bisa keluar dari sebuah aktivitas dan satu yang bisa masuk. Mana yang cocok bergantung pada satu pertanyaan: apakah pemain berada di dalam halamanmu, atau di tempat lain sepenuhnya?

Webhook hasil

Aktifkan "Kirim hasil ke webhook" di editor dan berikan sebuah URL. Sejak saat itu, setiap kali progres pemain disimpan, browser mereka mengirim (POST) seluruh hasil ke URL itu sebagai 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);
});

Hasil ke halaman di sekitarnya

Jika kamu menyematkan aktivitas ini, kamu bisa membuat JSON yang sama itu dikirim ke halamanmu sendiri, bukan ke server. Aktifkan "Kirim hasil ke halaman induk" dan dengarkan pesannya. Tidak ada yang keluar dari browser, jadi tidak perlu membangun endpoint dan tidak perlu memikirkan 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>

Sinyal penyelesaian

Saluran paling sederhana, untuk saat hasilnya sendiri bukan urusanmu: aktifkan "Kirim sinyal penyelesaian" dan halamanmu akan menerima satu pesan begitu pemain selesai.

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

Apa isi sebuah hasil

Satu bentuk yang sama, saluran apa pun yang membawanya. Jawaban pemain diberi kunci berdasarkan id item milik aktivitas itu sendiri, jadi kunci yang sama muncul juga di 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
}

Mengatur ulang aktivitas dari halamanmu

Satu instruksi berjalan ke arah sebaliknya. Dengan "Terima pemicu dari halaman induk" diaktifkan, halaman yang melakukan penyematan bisa menghapus jawaban pemain dan mengembalikan aktivitas ke awal — untuk tombol "coba lagi" milikmu sendiri, di luar frame.

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

Membawa identitas pemainmu sendiri

Jika platformmu sudah tahu siapa yang bermain, aktivitas tidak perlu menanyakannya lagi. Ada dua jenis handshake, keduanya untuk aktivitas di dalam halamanmu, dan keduanya diaktifkan oleh kami, bukan dari editor — karena keduanya menentukan hasil itu menjadi milik siapa, jadi pengaturannya dilakukan bersama kami, bukan lewat sebuah centang.

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

Membuat aktivitas dari sistemmu

Semua yang di atas soal hasil yang keluar. Ke arah sebaliknya — membuat aktivitasnya sendiri dari konten yang sudah kamu punya — itulah Puzzle API: satu POST per tipe aktivitas, dan kamu akan mendapatkan kembali sebuah kunci dan URL untuk disematkan.

Saat konektor siap pakai adalah jawaban yang lebih baik

Jika platform di sisi lain adalah LMS sungguhan, kemungkinan besar kamu tidak memerlukan semua ini. Nilai bisa langsung masuk ke buku nilainya sendiri, tanpa perlu kamu hosting apa pun.

Apa yang tidak ada

Supaya kamu tidak repot mencarinya:

• Tidak ada endpoint untuk membaca kembali hasil. API ini membuat aktivitas; hasil keluar lewat saluran-saluran di halaman ini, atau lewat ekspor di dasbormu.
• Tidak ada tanda tangan pada webhook. Tidak ada yang bisa dijadikan acuan untuk memverifikasi permintaannya, itulah sebabnya sebuah hasil tidak boleh menjadi satu-satunya dasar untuk sesuatu yang penting.
• Tidak ada webhook untuk seluruh akun. URL-nya adalah pengaturan pada satu aktivitas, jadi aktivitas yang kamu salin akan membawanya, sementara aktivitas baru dimulai tanpanya.
• Tidak berlaku pada permainan tim atau ruang langsung. Kedua saluran pesan dan webhook hanya untuk permainan solo, dan pengaturannya otomatis nonaktif saat mode tim diaktifkan.
• Tidak ada antrean pengiriman. Tidak ada yang disimpan lalu dikirim ulang — penyimpanan berikutnya berfungsi sebagai percobaan ulang, dan panggilan terakhir dari sesi itulah yang menjadi penentu.