Puzzel'i kendi platformuna bağla

Hangi kanala ihtiyacın var?

Bir etkinlikten çıkabilecek üç şey, içine girebilecek bir şey var. Hangisinin uyduğu tek bir soruya bağlı: oyuncu senin sayfanın içinde mi, yoksa tamamen başka bir yerde mi?

Sonuç webhook'u

Düzenleyicide "Sonuçları bir webhook'a gönder" ayarını aç ve bir URL ver. Bundan sonra oyuncunun ilerlemesi her kaydedildiğinde, tarayıcısı sonucun tamamını JSON olarak bu URL'ye POST eder.

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

Sonuçlar, onu çevreleyen sayfaya

Etkinliği yerleştirirsen, aynı JSON'ın bir sunucu yerine kendi sayfana gönderilmesini sağlayabilirsin. "Sonuçları üst sayfaya gönder" ayarını aç ve mesajı dinle. Tarayıcıdan hiçbir şey çıkmaz, yani kurulacak bir uç nokta ve düşünülecek bir CORS yoktur.

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

Bitiş sinyali

Sonucun kendisinin seni ilgilendirmediği durumlar için en küçük kanal: "Bitiş sinyali gönder" ayarını aç ve oyuncu bitirdiği anda sayfan tek bir mesaj alır.

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

Bir sonuç neler içerir

Hangi kanal taşırsa taşısın, tek bir şekil. Oyuncunun cevapları, etkinliğin kendi öğe kimlikleriyle anahtarlanır, bu yüzden aynı anahtarlar correctUids içinde de karşına çıkar.

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

Etkinliği sayfandan sıfırlamak

Bir talimat da diğer yöne gider. "Üst sayfadan gelen tetikleyicileri kabul et" ayarı açıkken, yerleştirmeyi yapan sayfa oyuncunun cevaplarını temizleyip etkinliği baştan başlatabilir — frame'in dışında kendi "tekrar dene" düğmen için.

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

Kendi oyuncu kimliğini kullanmak

Platformun kimin oynadığını zaten biliyorsa, etkinliğin bunu tekrar sorması gerekmez. İkisi de sayfanın içindeki bir etkinlik için olan ve düzenleyicide değil bizim tarafımızdan açılan iki el sıkışma vardır — bunlar bir sonucun kime ait olduğunu değiştirir, bu yüzden bir onay kutusundan değil seninle birlikte kurulur.

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

Etkinlikleri kendi sisteminden oluşturmak

Yukarıdakilerin hepsi bir sonucun çıkmasıyla ilgili. Diğer yönde gitmek — etkinliklerin kendisini zaten sahip olduğun içerikten oluşturmak — Puzzle API'sidir: etkinlik türü başına bir POST, karşılığında yerleştirmek için bir anahtar ve bir URL alırsın.

Hazır bir bağlayıcının daha iyi olduğu durumlar

Karşı taraftaki platform gerçek bir LMS ise büyük olasılıkla bunların hiçbirine ihtiyacın yoktur. Notlar, senin barındırman gereken hiçbir şey olmadan kendiliğinden not defterine geri döner.

Ne yok

Boşuna aramayasın diye:

• Sonuçları geri okumak için bir uç nokta yok. API etkinlikler oluşturur; sonuçlar bu sayfadaki kanallardan ya da panelindeki dışa aktarmalardan çıkar.
• Webhook'ta imza yok. İsteği doğrulayacak bir şey olmadığından, önemli bir şeyin arkasında tek dayanak bir sonuç olmamalı.
• Hesap genelinde bir webhook yok. URL, bir etkinliğin ayarıdır, bu yüzden kopyaladığın bir etkinlik onu da beraberinde taşır, yeni bir etkinlik ise onsuz başlar.
• Bir takım oyununda ya da canlı bir odada hiçbir şey yok. Her iki mesaj kanalı da webhook da tek başına oynamak içindir, takım oyunu açıkken ayarlar kendiliğinden kapanır.
• Bir teslimat kuyruğu yok. Hiçbir şey saklanıp yeniden gönderilmez — bir sonraki kayıt yeniden deneme demektir, önemli olan çalıştırmanın son çağrısıdır.