Σύνδεσε το Puzzel με τη δική σου πλατφόρμα

Ποιο κανάλι χρειάζεσαι;

Τρία πράγματα μπορούν να βγουν από μια δραστηριότητα και ένα μπορεί να μπει. Ποιο ταιριάζει εξαρτάται από μία μόνο ερώτηση: ο παίκτης βρίσκεται μέσα στη σελίδα σου, ή κάπου εντελώς αλλού;

Webhook αποτελεσμάτων

Ενεργοποίησε την επιλογή «Αποστολή αποτελεσμάτων σε webhook» στον επεξεργαστή και δώσε της ένα URL. Από τότε και μετά, κάθε φορά που αποθηκεύεται η πρόοδος του παίκτη, το πρόγραμμα περιήγησής του στέλνει με POST ολόκληρο το αποτέλεσμα σε αυτό το URL, ως 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);
});

Αποτελέσματα στη σελίδα γύρω της

Αν ενσωματώνεις τη δραστηριότητα, μπορείς να στέλνεις το ίδιο JSON στη δική σου σελίδα αντί σε έναν διακομιστή. Ενεργοποίησε την επιλογή «Αποστολή αποτελεσμάτων στη γονική σελίδα» και άκουσε για το μήνυμα. Τίποτα δεν φεύγει από το πρόγραμμα περιήγησης, οπότε δεν υπάρχει endpoint να φτιάξεις ούτε 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>

Σήμα ολοκλήρωσης

Το πιο μικρό κανάλι, για όταν το ίδιο το αποτέλεσμα δεν σε αφορά: ενεργοποίησε την επιλογή «Αποστολή σήματος ολοκλήρωσης» και η σελίδα σου παίρνει ένα μήνυμα τη στιγμή που ο παίκτης τελειώνει.

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

Τι περιέχει ένα αποτέλεσμα

Μία μορφή, όποιο κανάλι κι αν τη μεταφέρει. Οι απαντήσεις του παίκτη έχουν ως κλειδί τα δικά τους αναγνωριστικά αντικειμένων της δραστηριότητας, οπότε τα ίδια κλειδιά εμφανίζονται και στο 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
}

Επαναφορά της δραστηριότητας από τη σελίδα σου

Μία εντολή ταξιδεύει προς την αντίθετη κατεύθυνση. Με ενεργοποιημένη την επιλογή «Αποδοχή εντολών από τη γονική σελίδα», η σελίδα που κάνει την ενσωμάτωση μπορεί να καθαρίσει τις απαντήσεις του παίκτη και να επαναφέρει τη δραστηριότητα στην αρχή — για ένα δικό σου κουμπί «δοκίμασε ξανά», έξω από το πλαίσιο.

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

Φέρνοντας τη δική σου ταυτότητα παίκτη

Αν η πλατφόρμα σου ξέρει ήδη ποιος παίζει, η δραστηριότητα δεν χρειάζεται να τον ρωτήσει ξανά. Υπάρχουν δύο χειραψίες, και οι δύο για μια δραστηριότητα μέσα στη σελίδα σου, και οι δύο ενεργοποιούνται από εμάς αντί από τον επεξεργαστή — αλλάζουν σε ποιον ανήκει ένα αποτέλεσμα, γι' αυτό ρυθμίζονται μαζί σου αντί από ένα πλαίσιο επιλογής.

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

Δημιουργία δραστηριοτήτων από το σύστημά σου

Όλα τα παραπάνω αφορούν ένα αποτέλεσμα που βγαίνει προς τα έξω. Το αντίστροφο — να φτιάχνεις τις ίδιες τις δραστηριότητες από περιεχόμενο που έχεις ήδη — είναι το Puzzle API: ένα POST ανά τύπο δραστηριότητας, και παίρνεις πίσω ένα κλειδί και ένα URL για ενσωμάτωση.

Όταν μια έτοιμη σύνδεση είναι η καλύτερη απάντηση

Αν η πλατφόρμα από την άλλη πλευρά είναι ένα πραγματικό LMS, μάλλον δεν χρειάζεσαι τίποτα από όλα αυτά. Οι βαθμοί μπορούν να επιστρέψουν μόνοι τους στο βαθμολόγιό του, χωρίς να χρειάζεται να φιλοξενήσεις εσύ τίποτα.

Τι δεν υπάρχει

Για να μην το ψάχνεις:

• Κανένα endpoint για να διαβάσεις αποτελέσματα πίσω. Το API δημιουργεί δραστηριότητες· τα αποτελέσματα βγαίνουν μέσα από τα κανάλια αυτής της σελίδας, ή μέσα από τις εξαγωγές στον πίνακα ελέγχου σου.
• Καμία υπογραφή στο webhook. Δεν υπάρχει τίποτα να ελέγξεις το αίτημα απέναντί του, γι' αυτό ένα αποτέλεσμα δεν πρέπει να είναι το μόνο στήριγμα πίσω από κάτι σημαντικό.
• Κανένα webhook σε επίπεδο λογαριασμού. Το URL είναι ρύθμιση μιας δραστηριότητας, οπότε μια δραστηριότητα που αντιγράφεις το κουβαλά μαζί της και μια καινούρια ξεκινά χωρίς αυτό.
• Τίποτα σε ένα παιχνίδι ομάδων ή σε μια ζωντανή αίθουσα. Και τα δύο κανάλια μηνυμάτων και το webhook είναι για ατομικό παιχνίδι, και οι ρυθμίσεις απενεργοποιούνται μόνες τους όταν είναι ενεργό το παιχνίδι για πολλούς παίκτες.
• Καμία ουρά παράδοσης. Τίποτα δεν αποθηκεύεται και ξαναστέλνεται — η επόμενη αποθήκευση είναι η επανάληψη, και η τελευταία κλήση της προσπάθειας είναι αυτή που μετράει.