Esta versão (v0.7) ainda não foi publicada no npm.
Pular para o conteúdo

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:

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

ts
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 * 1000

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

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

ts
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).

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

ts
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 com UNAUTHENTICATED sem request.
  • Depois do login, chame createSession() e troque o src pela launchUrl. O connectFirstFrame relê a origem do src a cada mensagem, então o mesmo frame continua valendo; o FIRST recarrega e envia APP_READY de novo.
  • Trate a sportsbookUrl da configuração como qualquer URL recebida: use-a só se for http(s) absoluta e sem credenciais. Se a sua configuração também traz config.widgetUrl, o app player a repassa ao FIRST no parâmetro api da 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 launchUrl antiga 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)HandlerArgumento
APP_READYonReady()nenhum
BET_WAS_PLACEDonBetPlaced(data)eventData
INSUFFICIENT_FUNDSonInsufficientFunds(data)eventData
depositClickonDepositClick(data)eventData
PLACE_BET_CLICKED_NOT_LOGGED_IN, OPEN_LOGIN_POPUPonLoginRequired(data)eventData
on-page-height-change, ON_PAGE_HEIGHT_CHANGEonHeightChange(height)eventData.height (ou height no topo da mensagem); só números positivos
BUTTON_REDIRECTonRedirect(data){ link?: string } (o link vem no topo da mensagem e pode faltar)
SCROLL_TO_TOPonScrollToTop()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, messageToParentsó onEventeventData

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:

eventTypeeventData
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ódigoQuando
UNAUTHENTICATEDsem 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_ERRORlaunch_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.