Referência postMessage

O SDK de incorporação implementa este protocolo para você. Continue lendo se você integra sem o SDK ou quer saber exatamente o que atravessa a fronteira do frame. As definições TypeScript estão em @bookmaker/embed-sdk/protocol.

Envelope

Toda mensagem é um objeto simples:

// iframe -> sua página (eventos)
{ source: 'bookmaker-sportsbook', v: 1, type: 'balance_changed', payload: { balance: 49500, currency: 'USD' } }

// sua página -> iframe (comandos)
{ source: 'bookmaker-host', v: 1, type: 'navigate', payload: { path: '/live' } }

payload é sempre um objeto ({} quando não há o que dizer). Valores são inteiros em unidades menores.

Regras de origem

Direção	Regra
iframe → página	Eventos só são enviados para a origem da página pai, depois de conferida contra os `embedOrigins` do tenant (ou de ser a própria origem do sportsbook). Nunca `'*'`. Nada é enviado antes dessa conferência, nem mesmo o `ready`.
página → iframe	Comandos só são aceitos da janela pai (`event.source === window.parent`) nessa origem verificada, com `source: 'bookmaker-host'`. Todo o resto é ignorado em silêncio.
Seu listener	Aceite uma mensagem só se `event.source` for o `contentWindow` do iframe do sportsbook, `event.origin` for exatamente a origem do sportsbook, `source` for `'bookmaker-sportsbook'` e `v` for `1`.
Seus comandos	`iframe.contentWindow.postMessage(mensagem, '<origem do sportsbook>')`, com a origem exata como `targetOrigin`.

Como o iframe sabe quem é o pai: location.ancestorOrigins, nos navegadores que o oferecem (Chromium, Safari); senão, o parâmetro origin que o SDK adiciona, ou a origem em document.referrer. Uma página que mente sobre a própria origem não ganha nada: o navegador só entrega eventos a um pai que tem de fato a origem declarada, e o frame-ancestors já impede que o sportsbook seja exibido em uma página não permitida.

Eventos

Enviados pelo iframe. O ready é sempre o primeiro; eventos ocorridos antes dele (por exemplo, um launch token recusado) ficam em fila e são enviados logo depois.

Evento	Payload	Quando
`ready`	`{ version: 1, tenant, locale, loggedIn: boolean, path }`	O sportsbook verificou a sua origem e aceita comandos. Uma vez por carregamento.
`resize`	`{ height }`	A altura do documento, em pixels CSS, mudou. No modo `auto` o SDK ajusta o iframe a partir dela.
`route`	`{ path, title }`	O jogador navegou. `title` vem no idioma atual, por exemplo `Flamengo x Palmeiras`, `Ao Vivo`. Uma página de evento informa de novo quando o título fica conhecido.
`login_required`	`{ reason: 'place_bet' \| 'my_bets' \| 'login' }`	Um jogador anônimo clicou em Entre para apostar, abriu Minhas Apostas ou clicou em Entrar. Abra o seu login e depois envie `set_launch_token`.
`session_expired`	`{ reason }`	A sessão terminou no servidor: `idle_timeout`, `expired`, `mfa_stale`, `logout` (encerrada em outro lugar), `account_blocked` ou `self_exclusion`; ou um launch token da URL foi recusado (`launch_token_used`, `launch_token_expired`, `launch_token_invalid`, `launch_failed`). O jogador fica anônimo até você enviar um novo launch token.
`balance_changed`	`{ balance, currency }`	O saldo da carteira ficou conhecido ou mudou: após o login, após cada débito e crédito da plataforma e em resposta a `refresh_balance`.
`bet_placed`	`{ betId, stake, potentialPayout, currency }`	Uma aposta foi aceita. Um evento por aposta quando um boletim faz várias.
`bet_settled`	`{ betId, status, payout, currency }`	Uma aposta chegou a um status final com o iframe aberto: `won`, `lost`, `void`, `cashed_out` ou `cancelled`. Enviado de novo se uma reliquidação o mudar.
`deposit_requested`	`{}`	O jogador clicou em Depositar. Abra o seu caixa e depois envie `refresh_balance`.
`error`	`{ code, message }`	Veja os códigos de erro.

Comandos

Enviados pela sua página. Comandos que chegam antes do ready não são processados: espere por ele (o SDK enfileira para você).

Comando	Payload	Efeito
`set_launch_token`	`{ launchToken }`	Troca o token e faz o login do jogador, ou substitui uma sessão expirada, sem recarregar. O boletim é mantido.
`navigate`	`{ path }`	Vai para um link direto: `/`, `/live`, `/live/{sportId}`, `/sport/{sportId}`, `/competition/{id}`, `/event/{eventId}`, `/my-bets`.
`set_locale`	`{ locale }`	`en` ou `pt-BR` (sem diferenciar maiúsculas). Redesenha no lugar.
`refresh_balance`	`{}`	Relê o saldo da sua carteira e responde com `balance_changed`.
`logout`	`{}`	Encerra a sessão do sportsbook no servidor e no iframe. Não há `session_expired` em seguida (a não ser que a sessão já tivesse terminado).

Códigos de erro

`code`	Significado
`launch_token_invalid`	Desconhecido, malformado ou de outro tenant.
`launch_token_used`	Já trocado: launch tokens são de uso único.
`launch_token_expired`	Mais antigo que 120 segundos.
`launch_failed`	O token não pôde ser trocado (erro de rede ou do servidor).
`invalid_command`	Tipo de comando desconhecido, ou campo de payload ausente ou inválido.
`invalid_path`	Não é um link direto do sportsbook (de `navigate` ou do parâmetro `path`).
`unsupported_locale`	Não é `en` nem `pt-BR` (de `set_locale` ou do parâmetro `locale`).
`unsupported_version`	O `v` do comando não é uma versão que este sportsbook fala.
`command_failed`	Um comando não pôde ser concluído, por exemplo o pacote de idioma de `set_locale` não carregou.

Versionamento

v é a versão principal do protocolo. Só muda em mudanças incompatíveis, e uma nova versão principal vem com uma nova URL do SDK (/embed/v2.js); a v1 continua funcionando.
Dentro da v1 podem surgir novos eventos, novos comandos e novos campos opcionais nos payloads. Ignore tipos de evento e campos que você não conhece. O SDK faz isso.
Campos de payload nunca são removidos nem mudam de tipo dentro da v1.
As mudanças ficam no changelog.