Sportsbook (FIRST)
Carregando a demo interativa…
A demo acima chama createSession de verdade (com createMockFetch e as rotas de @getenginex/sdk-igaming/testing) e conecta o iframe com o connectFirstFrame real. O FIRST é uma simulação: o quadro é uma página estática deste site (demos/first-frame.html) que envia os mesmos eventos postMessage do FIRST. Ela está na mesma origem do src, então o helper aceita as mensagens sem enfraquecer a checagem de origem (um srcdoc ou about:blank seria recusado de propósito). Clique nos botões dentro do quadro: BET_WAS_PLACED recarrega o saldo por HTTP, INSUFFICIENT_FUNDS mostra o CTA de depósito, BUTTON_REDIRECT passa pela validação do link (o link perigoso é recusado) e os botões send enviam comandos ao quadro. A launchUrl tem o token de operador mascarado na tela e no painel Under the hood.
O namespace sportsbook de @getenginex/sdk-igaming cria a sessão do sportsbook FIRST do jogador logado: o gateway gera um token de operador de curta duração e devolve a URL que o app carrega num iframe. createSession exige login (enginex.auth.login); o visitante sem login também pode ver o sportsbook, pela URL pública da configuração (veja Visitante sem login). Em testes, withIgamingRoutes já responde à rota (veja Testes).
1. Confirme que o FIRST está ativo
A configuração do sportsbook é do core (enginex.config.getSportsbook(), pública). O gateway responde 400 em createSession quando o FIRST não está habilitado para o operador; checar antes evita a chamada e deixa a tela decidir o que mostrar:
const sportsbook = await enginex.config.getSportsbook()
if (!sportsbook.enabled || sportsbook.provider !== 'first') {
// another provider (or none): do not use createSession
}2. Crie a sessão
import { createIgaming } from '@getenginex/sdk-igaming'
const igaming = createIgaming(enginex)
const session = await igaming.sportsbook.createSession()
session.launchUrl // sportsbook URL, with the operator token in the query
session.expiresInSeconds // validity counted from the response (24 h on the default gateway)
session.expiresAt // ms since the epoch: client clock at the response + expiresInSeconds * 1000O token de operador não aparece no resultado: ele só existe dentro de launchUrl. Por isso a URL é tratada como sensível, como a gameUrl do cassino: nenhum hook (onRequest, onResponse, onError) nem onValidationIssue recebe a URL, e a resposta é validada sempre em modo estrito. launchUrl que não seja http(s) absoluta ou expiresInSeconds menor ou igual a zero viram VALIDATION_ERROR. Não registre a URL em logs, analytics nem rastreamento de erros.
3. Reutilize até expiresAt - 30 s
O SDK não faz cache: cada chamada gera um token novo. Guarde a sessão em memória no app e só crie outra perto de expirar:
let session: SportsbookSession | undefined
async function currentSession() {
if (!session || Date.now() >= session.expiresAt - 30_000) {
session = await igaming.sportsbook.createSession()
}
return session
}Ao trocar de usuário (logout/login), descarte a sessão: o token é do jogador que a criou.
4. Monte o iframe
const { launchUrl } = await currentSession()
const iframe = document.createElement('iframe')
iframe.src = launchUrl
iframe.style.width = '100%'
iframe.style.border = '0'
container.append(iframe)5. Eventos do iframe
O FIRST conversa com a página por postMessage. O helper opcional connectFirstFrame, do entry @getenginex/sdk-igaming/first-frame, recebe esses eventos em handlers tipados e envia comandos ao iframe. É um entry à parte: quem importa só createIgaming não o leva no bundle, e ele não importa o core em runtime (nem exige lib.dom nos seus tipos).
import { connectFirstFrame } from '@getenginex/sdk-igaming/first-frame'
const frame = connectFirstFrame(iframe, {
onReady: () => frame.send('home', { value: true }),
onBetPlaced: () => void enginex.wallet.getBalance().then(showBalance),
onLoginRequired: () => openLoginModal(),
onInsufficientFunds: () => goToDeposit(),
onHeightChange: (height) => (iframe.style.height = `${height}px`),
onRedirect: (data) => openSafely(data),
})
// when unmounting the iframe (or switching users):
frame.dispose()Visitante sem login
O iframe do FIRST também carrega anônimo: o visitante navega pelos eventos e odds e, quando tenta apostar, o FIRST pede o login. Para isso não há sessão: use a URL pública da configuração, config.sportsbookUrl de enginex.config.getSportsbook() (rota pública, sem token). É o que o app player faz.
const sportsbook = await enginex.config.getSportsbook()
const publicUrl = sportsbook.enabled && sportsbook.provider === 'first' ? sportsbook.config?.sportsbookUrl : undefined
async function sportsbookUrl(): Promise<string | undefined> {
// logged in: the player's session (with the operator token); visitor: public URL, no token
if (enginex.session.get().status === 'authenticated') return (await currentSession()).launchUrl
return publicUrl
}
iframe.src = (await sportsbookUrl()) ?? 'about:blank'
const frame = connectFirstFrame(iframe, {
// PLACE_BET_CLICKED_NOT_LOGGED_IN or OPEN_LOGIN_POPUP: the visitor tried to bet
onLoginRequired: () => openLoginModal(),
})
// after login (and on logout), swap the URL of the same iframe
let userId = enginex.session.get().userId
enginex.session.subscribe(async (current) => {
if (current.userId === userId) return // token refresh for the same user: nothing changes
userId = current.userId
session = undefined // the FIRST session belongs to the player who created it
iframe.src = (await sportsbookUrl()) ?? 'about:blank'
})- Antes do login nenhuma chamada autenticada é feita:
createSession()sem sessão rejeita comUNAUTHENTICATEDsem request. - Depois do login, chame
createSession()e troque osrcpelalaunchUrl. OconnectFirstFramerelê a origem dosrca cada mensagem, então o mesmoframecontinua valendo; o FIRST recarrega e enviaAPP_READYde novo. - Trate a
sportsbookUrlda configuração como qualquer URL recebida: use-a só se for http(s) absoluta e sem credenciais. Se a sua configuração também trazconfig.widgetUrl, o app player a repassa ao FIRST no parâmetroapida URL pública (url.searchParams.set('api', widgetUrl)), só quando éhttps. - A URL pública não leva token de operador. Não reaproveite uma
launchUrlantiga para o visitante: ela é a sessão de um jogador.
Segurança
O helper só entrega uma mensagem se event.source === iframe.contentWindow e event.origin é a origem do iframe.src (relida a cada mensagem). Origem diferente, outra janela, JSON inválido ou mensagem sem eventType são ignorados, sem lançar. send posta sempre para a origem do src, nunca para '*': se o src não tem origem http(s) válida, ou depois de dispose(), lança CONFIGURATION_ERROR (sem incluir o src, que carrega o token). Um handler que lança não derruba o listener nem impede os outros. Os payloads chegam como unknown, exatamente como o FIRST os enviou: valide antes de usar. Em especial, onRedirect recebe { link?: string } (o link pode faltar; um link que não seja texto é descartado pelo helper): abra o link só se existir, for http(s) e sem credenciais (window.open(link, '_blank', 'noopener,noreferrer')).
Por padrão o helper ouve em globalThis (a janela da página que contém o iframe); passe { window } como terceiro argumento para outra janela ou fora do browser.
Eventos recebidos
O evento vem em eventType (o helper aceita também a chave type). onEvent(eventType, eventData) é chamado para todo evento aceito, inclusive os que têm handler dedicado.
Evento do FIRST (eventType) | Handler | Argumento |
|---|---|---|
APP_READY | onReady() | nenhum |
BET_WAS_PLACED | onBetPlaced(data) | eventData |
INSUFFICIENT_FUNDS | onInsufficientFunds(data) | eventData |
depositClick | onDepositClick(data) | eventData |
PLACE_BET_CLICKED_NOT_LOGGED_IN, OPEN_LOGIN_POPUP | onLoginRequired(data) | eventData |
on-page-height-change, ON_PAGE_HEIGHT_CHANGE | onHeightChange(height) | eventData.height (ou height no topo da mensagem); só números positivos |
BUTTON_REDIRECT | onRedirect(data) | { link?: string } (o link vem no topo da mensagem e pode faltar) |
SCROLL_TO_TOP | onScrollToTop() | nenhum |
bet-in-process, BET_IN_PROCESS, reserve-error, UPDATE_BETS_COUNT, BETSLIP_OPEN, BETSLIP_CLOSE, shareBetslip ({ code }), LOCATION_CHANGE, POPUP_STATE_CHANGE, LANGUAGE_CHANGED, languageChange, messageToParent | só onEvent | eventData |
Comandos enviados
frame.send(eventType, eventData?) posta { eventType, eventData } (em JSON) ao iframe. Espere onReady antes de enviar: o FIRST só ouve depois de carregar. Os comandos que o FIRST entende:
eventType | eventData |
|---|---|
sportId, leagueId, eventId | { value: id } |
liveBetting, home | { value: true } |
betting-history, open-bets, expand-bet-slip | { value: boolean } |
bscode | { value: código } (carrega um cupom compartilhado) |
shareBetslip | { url } (resposta ao shareBetslip recebido) |
Erros
| Código | Quando |
|---|---|
UNAUTHENTICATED | sem sessão (nenhum request é feito); para o visitante, use a URL pública |
INVALID_ARGUMENT (400) | FIRST não habilitado para o operador (use o code do envelope) |
UNAVAILABLE (503) | configuração do FIRST incompleta, serviço de sessão fora do ar ou configuração de sportsbook do serviço de apostas indisponível |
VALIDATION_ERROR | launch_url não http(s) absoluta ou expires_in_seconds não positivo |
Identifique pelo código: isEnginexError(error, 'UNAVAILABLE').
Testes
A rota mock GET /first/session (com login) devolve https://first.mock.local/sportsbook?operatorToken=... com validade de 24 h e um token novo a cada chamada.