Conecte o Puzzel à sua própria plataforma

De qual canal você precisa?

Três coisas podem sair de uma atividade e uma pode entrar. Qual delas serve depende de uma única pergunta: o jogador está dentro da sua página ou em outro lugar completamente diferente?

Webhook de resultados

Ative "Enviar resultados para um webhook" no editor e informe uma URL. A partir daí, toda vez que o progresso do jogador for salvo, o navegador dele envia por POST o resultado inteiro para essa URL, como 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);
});

Resultados para a página ao redor

Se você incorporar a atividade, pode fazer com que esse mesmo JSON seja enviado para a sua própria página em vez de para um servidor. Ative "Enviar resultados para a página pai" e escute a mensagem. Nada sai do navegador, então não há endpoint para construir nem CORS para se preocupar.

<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 menor canal, para quando o resultado em si não é da sua conta: ative "Enviar um sinal de conclusão" e sua página recebe uma mensagem no exato 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 um resultado contém

Um único formato, seja qual for o canal que o carrega. As respostas do jogador são indexadas pelos próprios ids dos itens da atividade, então 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
}

Reiniciando a atividade a partir da sua página

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

Trazendo sua própria identidade de jogador

Se sua plataforma já sabe quem está jogando, a atividade não precisa perguntar de novo. Existem dois handshakes, ambos para uma atividade dentro da sua página, e ambos ativados por nós em vez de no editor — eles mudam a quem um resultado pertence, então são configurados junto com você, e não por uma caixa de seleçã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();
});

Criando atividades a partir do seu sistema

Tudo acima é sobre um resultado saindo. Na direção oposta — criar as próprias atividades a partir de um conteúdo que você já tem — está a Puzzle API: um POST por tipo de atividade, e você recebe de volta uma chave e uma URL para incorporar.

Quando um conector pronto é a resposta melhor

Se a plataforma do outro lado é um LMS de verdade, provavelmente você não precisa de nada disso. As notas podem voltar sozinhas para o diário de classe dele, sem nada para você hospedar.

O que não existe

Para você não sair procurando por isso:

• Nenhum endpoint para ler resultados de volta. A API cria atividades; os resultados saem pelos canais desta página, ou pelas exportações no seu painel.
• Nenhuma assinatura no webhook. Não há nada contra o que verificar a requisição, por isso um resultado não deveria ser a única coisa sustentando algo importante.
• Nenhum webhook para a conta inteira. A URL é uma configuração da atividade, então uma atividade que você copia leva a configuração junto, e uma nova começa sem ela.
• Nada em um jogo em equipe ou em uma sala ao vivo. Tanto os canais de mensagem quanto o webhook são para o jogo individual, e as configurações se desativam sozinhas quando o modo em equipe está ativado.
• Nenhuma fila de entrega. Nada é armazenado e reenviado — o próximo salvamento é a nova tentativa, e a última chamada da tentativa é a que importa.