Collega Puzzel alla tua piattaforma

Di quale canale hai bisogno?

Tre cose possono uscire da un'attività e una può entrare. Quale ti serve dipende da una sola domanda: il giocatore si trova dentro la tua pagina, oppure altrove?

Webhook dei risultati

Attiva "Invia i risultati a un webhook" nell'editor e indica un URL. Da quel momento, ogni volta che i progressi del giocatore vengono salvati, il suo browser invia in POST l'intero risultato a quell'URL, come 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);
});

Risultati alla pagina che la circonda

Se incorpori l'attività, puoi far arrivare lo stesso JSON alla tua pagina invece che a un server. Attiva "Invia i risultati alla pagina principale" e resta in ascolto del messaggio. Nulla esce dal browser, quindi non c'è nessun endpoint da costruire e nessun CORS di cui preoccuparti.

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

Segnale di completamento

Il canale più piccolo, per quando il risultato in sé non ti riguarda: attiva "Invia un segnale di completamento" e la tua pagina riceve un messaggio nel momento in cui il giocatore finisce.

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

Cosa contiene un risultato

Una sola struttura, qualunque sia il canale che la trasporta. Le risposte del giocatore sono indicizzate dagli id degli elementi dell'attività, quindi le stesse chiavi compaiono anche in 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
}

Azzerare l'attività dalla tua pagina

Un'istruzione viaggia nella direzione opposta. Con "Accetta comandi dalla pagina principale" attivato, la pagina che esegue l'incorporamento può cancellare le risposte del giocatore e riportare l'attività all'inizio — per un tuo pulsante "riprova" esterno al 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');

Portare la propria identità del giocatore

Se la tua piattaforma sa già chi sta giocando, l'attività non deve chiederglielo di nuovo. Esistono due handshake, entrambi per un'attività dentro la tua pagina, ed entrambi attivati da noi anziché nell'editor — cambiano a chi appartiene un risultato, quindi vengono configurati insieme a te e non da una casella di spunta.

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

Creare attività dal tuo sistema

Tutto quanto sopra riguarda un risultato in uscita. Fare il percorso inverso — creare le attività stesse a partire da contenuti che hai già — è compito della Puzzle API: un POST per ogni tipo di attività, e in cambio ricevi una chiave e un URL da incorporare.

Quando un connettore già pronto è la soluzione migliore

Se la piattaforma dall'altra parte è un vero LMS, probabilmente non ti serve niente di tutto questo. I voti possono tornare da soli al suo registro, senza che tu debba ospitare nulla.

Cosa non c'è

Così non lo cerchi invano:

• Nessun endpoint per rileggere i risultati. La API crea le attività; i risultati escono tramite i canali di questa pagina, oppure tramite le esportazioni nella tua dashboard.
• Nessuna firma sul webhook. Non c'è nulla su cui verificare la richiesta, ed è per questo che un risultato non dovrebbe essere l'unica cosa a garantire qualcosa di importante.
• Nessun webhook a livello di account. L'URL è un'impostazione di una singola attività, quindi un'attività che copi la porta con sé, mentre una nuova ne parte priva.
• Niente in un gioco a squadre o in una stanza dal vivo. Sia i canali a messaggi sia il webhook sono pensati per il gioco singolo, e le impostazioni si disattivano da sole quando il gioco a squadre è attivo.
• Nessuna coda di consegna. Niente viene memorizzato e reinviato — il prossimo salvataggio funge da nuovo tentativo, e l'ultima chiamata del tentativo è quella che conta.