Liga o Puzzel à tua própria plataforma

De que canal precisas?

Há três coisas que podem sair de uma atividade e uma que pode entrar. A que serve depende de uma única pergunta: o jogador está dentro da tua página, ou completamente noutro lado?

Webhook de resultados

Ativa "Enviar os resultados para um webhook" no editor e indica um URL. A partir daí, sempre que o progresso do jogador é guardado, o navegador dele envia o resultado completo por POST, em JSON, para esse URL.

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

Resultados para a página que a envolve

Se incorporares a atividade, podes ter esse mesmo JSON enviado para a tua própria página em vez de para um servidor. Ativa "Enviar os resultados para a página principal" e fica à escuta da mensagem. Nada sai do navegador, por isso não há endpoint para construir nem CORS a considerar.

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

Sinal de conclusão

O canal mais pequeno, para quando o resultado em si não te diz respeito: ativa "Enviar um sinal de conclusão" e a tua página recebe uma mensagem no momento em que o jogador termina.

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

O que contém um resultado

Uma única forma, seja qual for o canal que a transporta. As respostas do jogador são indexadas pelos ids dos próprios itens da atividade, por isso as mesmas chaves aparecem em 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
}

Reiniciar a atividade a partir da tua página

Uma instrução viaja no sentido contrário. Com "Aceitar comandos da página principal" ativado, a página que faz a incorporação pode limpar as respostas do jogador e voltar a colocar a atividade no início — para um botão "tentar novamente" teu, fora da 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');

Trazer a tua própria identidade de jogador

Se a tua plataforma já sabe quem está a jogar, a atividade não precisa de perguntar outra vez. Existem dois handshakes, ambos para uma atividade dentro da tua página, e ambos ativados por nós em vez de no editor — mudam a quem pertence um resultado, por isso são configurados contigo em vez de a partir de uma caixa de verificação.

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

Criar atividades a partir do teu sistema

Tudo o que foi dito acima é sobre um resultado a sair. No sentido contrário — criar as próprias atividades a partir de conteúdo que já tens — está a Puzzle API: um POST por tipo de atividade, e recebes de volta uma chave e um URL para incorporar.

Quando um conector já feito é a melhor resposta

Se a plataforma do outro lado for um LMS a sério, provavelmente não precisas de nada disto. As notas podem voltar sozinhas para o livro de notas, sem nada que precises de alojar.

O que não existe

Para não andares à procura disso:

• Não há endpoint para ler resultados de volta. A API cria atividades; os resultados saem através dos canais desta página, ou através das exportações no teu painel.
• Não há assinatura no webhook. Não há nada contra o qual verificar o pedido, e é por isso que um resultado não deve ser a única coisa a sustentar algo que importa.
• Não há webhook à escala da conta. O URL é uma definição de uma atividade, por isso uma atividade que copias transporta-o consigo e uma nova começa sem ele.
• Nada num jogo em equipa ou numa sala ao vivo. Tanto os canais de mensagens como o webhook são para jogo a solo, e as definições desativam-se sozinhas quando o modo de equipas está ativado.
• Não há fila de entrega. Nada é guardado e reenviado — o próximo guardar é a nova tentativa, e a última chamada da partida é a que conta.