---
name: integrar-trofeus-gpb
description: Integrar conquistas reais de jogos web ao SDK de testes do Gamers pelo Brasil, preservando retries e resgate central. Usar ao conectar callbacks de jogos externos ou avaliar a integração de um jogo hospedado; não cobre cadastro administrativo nem publicação.
---

# Integrar troféus GPB

Distribuição oficina-2026-10-23.1, SDK 0.1.0-test.3. Leia o [guia](references/guia.md)
e o [exemplo completo](references/exemplo.html) antes de editar. O guia é gerado de
backend/sdk/README.md, dono do contrato; [módulo](references/trofeus.js) e exemplo
são cópias exatas da revisão distribuída. O [OpenAPI](references/openapi.yaml)
retrata a implementação local, sem garantir disponibilidade pública.

## Identificar o perfil

Inspecione o chamador real e as condições de execução antes de escolher o caminho.

- **Externo, origem própria:** use API, chave pública e origens exatas fornecidas
  pelo operador. Se faltarem, peça esses dados e continue o mapeamento de callbacks
  independente da rede. Não invente endereço público nem cadastre chaves.
- **Hospedado, nova aba com origem opaca:** o SDK direto não é a integração entregue.
  Todos os jogos abrem diretamente em nova aba após a apresentação. É necessária
  uma integração própria revisada, ainda pendente, com validação do emissor e slots.
  Preserve o sandbox HTTP: não autorize Origin null, allow-same-origin, rede ou
  storage como atalho. Prepare o mapeamento e descreva a dependência; só declare
  integrado depois de exercitar o chamador real e o resgate.


## Ligar conquistas sem perder recuperação

Mapeie desafios existentes para slots do guia; não invente regras de vitória.
Reutilize a UI e registrarConquista(slot) do exemplo em vez de reduzir a chamada
a um snippet sem recuperação. Prepare o SDK antes de jogar. O callback pode
ocorrer uma única vez: mantenha intenção antes do envio, linhas independentes,
retry disponível após erro/reload e retomada com a mesma API/chave.

Retry usa ganhar(slot) e a mesma prova. Renovar usa renovarLink(slot) somente
por ação explícita; não substitua token por timeout, erro ou perda de resposta.
Preserve pendentes(), controle de concorrência e links separados por slot.
Não confunda intenção local ou link pronto com conquista resgatada.
Envie só conquistas: preserve credentials: 'omit', sem score, diário, IDs de
jogador, cookies ou login no jogo. Não registre tokens ou links pessoais em logs.

## Validar e explicar o alcance

Comece com `testar(slot)` e a chave pública: funciona em localhost sem cadastro,
verifica conexão/chave/slot e não grava claim ou troféu. Preserve `persisted: false`
e a indicação de `origin_registered`; não invente links no diagnóstico.
`ganhar(slot)` emite provas reais e continua exigindo origem cadastrada.


Com a API de testes fornecida, exercite um callback natural, dois slots, resposta
perdida/falha de rede, retry, reload, renovação explícita e resgate central.
Confira a coleção recuperada e persistência com o operador; HTTP 200 sozinho
não prova o efeito no banco. Declare exatamente o que não pôde executar.

O pacote não foi publicado no npm. A API de testes está publicada; use os dados
fornecidos pelo operador. Login Google depende da configuração da central. No
modo de identidade de teste, perda ou expiração do cookie não recupera a coleção. A chave pública não prova
vitória; o link é ao portador. Storage indisponível mantém intenção só em memória.
Os detalhes e limites pertencem ao guia, sem uma segunda especificação aqui.
Entregue as alterações, como testá-las e dependências restantes; cadastro, proxy,
conta recuperável, push e deploy ficam fora desta skill.

### Aceite com o criador

Siga o roteiro de validação do guia: diagnóstico sem gravação, simulação no jogo
com envio interceptado e aceite real com conta são etapas diferentes. Falha
provocada com mensagem de retry é esperada; confira o reenvio e a retomada após
reload. No ambiente controlado, perca a resposta depois de a API aceitar a
emissão e confira a mesma prova, sem duplicação, em dois slots independentes.
O aceite público exige callback natural e resgate/coleção com conta em celular,
incluindo retorno do login e coleção recuperada em outro navegador. Registre
versão, slot, data/hora, dispositivo e resultado sem tokens ou links pessoais.
Títulos/descrições próprios podem ficar no jogo; a central atual mostra categoria
e jogo. Personalização não bloqueia o piloto e não autoriza novos campos na API.