Sportsbook (FIRST)
Cargando la demo interactiva…
La demo de arriba llama a createSession de verdad (con createMockFetch y las rutas de @getenginex/sdk-igaming/testing) y conecta el iframe con el connectFirstFrame real. FIRST es una simulación: el marco es una página estática de este sitio (demos/first-frame.html) que envía los mismos eventos postMessage de FIRST. Está en el mismo origen que el src, así que el helper acepta los mensajes sin debilitar la verificación de origen (un srcdoc o about:blank se rechazaría a propósito). Haz clic en los botones dentro del marco: BET_WAS_PLACED recarga el saldo por HTTP, INSUFFICIENT_FUNDS muestra el CTA de depósito, BUTTON_REDIRECT pasa por la validación del enlace (el enlace peligroso se rechaza) y los botones send envían comandos al marco. La launchUrl tiene el token de operador enmascarado en pantalla y en el panel Under the hood.
El namespace sportsbook de @getenginex/sdk-igaming crea la sesión del sportsbook FIRST del jugador con sesión iniciada: el gateway genera un token de operador de corta duración y devuelve la URL que la app carga en un iframe. createSession exige inicio de sesión (enginex.auth.login); el visitante sin sesión también puede ver el sportsbook, por la URL pública de la configuración (consulta Visitante sin sesión). En pruebas, withIgamingRoutes ya responde la ruta (consulta Pruebas).
1. Confirma que FIRST está activo
La configuración del sportsbook es del core (enginex.config.getSportsbook(), pública). El gateway responde 400 en createSession cuando FIRST no está habilitado para el operador; comprobarlo antes evita la llamada y deja que la pantalla decida qué mostrar:
const sportsbook = await enginex.config.getSportsbook()
if (!sportsbook.enabled || sportsbook.provider !== 'first') {
// another provider (or none): do not use createSession
}2. Crea la sesión
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 * 1000El token de operador no aparece en el resultado: solo existe dentro de launchUrl. Por eso la URL se trata como sensible, igual que la gameUrl del casino: ningún hook (onRequest, onResponse, onError) ni onValidationIssue recibe la URL, y la respuesta se valida siempre en modo estricto. Una launchUrl que no sea http(s) absoluta o un expiresInSeconds menor o igual a cero se convierten en VALIDATION_ERROR. No registres la URL en logs, analytics ni en el seguimiento de errores.
3. Reutiliza hasta expiresAt - 30 s
El SDK no hace caché: cada llamada genera un token nuevo. Guarda la sesión en memoria en la app y crea otra solo cerca de que expire:
let session: SportsbookSession | undefined
async function currentSession() {
if (!session || Date.now() >= session.expiresAt - 30_000) {
session = await igaming.sportsbook.createSession()
}
return session
}Al cambiar de usuario (logout/login), descarta la sesión: el token es del jugador que la creó.
4. Monta el 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 del iframe
FIRST se comunica con la página por postMessage. El helper opcional connectFirstFrame, del entry @getenginex/sdk-igaming/first-frame, recibe esos eventos en handlers tipados y envía comandos al iframe. Es un entry aparte: quien importa solo createIgaming no lo lleva en el bundle, y no importa el core en runtime (ni exige lib.dom en sus 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 sin sesión
El iframe de FIRST también carga de forma anónima: el visitante navega por los eventos y las cuotas y, cuando intenta apostar, FIRST pide iniciar sesión. Para eso no hay sesión: usa la URL pública de la configuración, config.sportsbookUrl de enginex.config.getSportsbook() (ruta pública, sin token). Es lo que hace la app player.
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 del inicio de sesión no se hace ninguna llamada autenticada:
createSession()sin sesión se rechaza conUNAUTHENTICATEDsin request. - Después del inicio de sesión, llama a
createSession()y cambia elsrcpor lalaunchUrl.connectFirstFramerelee el origen delsrcen cada mensaje, así que el mismoframesigue valiendo; FIRST se recarga y envíaAPP_READYde nuevo. - Trata la
sportsbookUrlde la configuración como cualquier URL recibida: úsala solo si es http(s) absoluta y sin credenciales. Si tu configuración también traeconfig.widgetUrl, la app player se la pasa a FIRST en el parámetroapide la URL pública (url.searchParams.set('api', widgetUrl)), solo cuando eshttps. - La URL pública no lleva token de operador. No reutilices una
launchUrlantigua para el visitante: es la sesión de un jugador.
Seguridad
El helper solo entrega un mensaje si event.source === iframe.contentWindow y event.origin es el origen de iframe.src (releído en cada mensaje). Un origen distinto, otra ventana, JSON inválido o un mensaje sin eventType se ignoran, sin lanzar excepción. send siempre envía al origen del src, nunca a '*': si el src no tiene un origen http(s) válido, o después de dispose(), lanza CONFIGURATION_ERROR (sin incluir el src, que lleva el token). Un handler que lanza una excepción no derriba el listener ni impide a los demás. Los payloads llegan como unknown, exactamente como FIRST los envió: valida antes de usar. En especial, onRedirect recibe { link?: string } (el link puede faltar; un link que no sea texto lo descarta el helper): abre el enlace solo si existe, es http(s) y no tiene credenciales (window.open(link, '_blank', 'noopener,noreferrer')).
Por defecto el helper escucha en globalThis (la ventana de la página que contiene el iframe); pasa { window } como tercer argumento para otra ventana o fuera del navegador.
Eventos recibidos
El evento viene en eventType (el helper acepta también la clave type). onEvent(eventType, eventData) se llama para todo evento aceptado, incluidos los que tienen un handler dedicado.
Evento de FIRST (eventType) | Handler | Argumento |
|---|---|---|
APP_READY | onReady() | ninguno |
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 (o height en la raíz del mensaje); solo números positivos |
BUTTON_REDIRECT | onRedirect(data) | { link?: string } (el link viene en la raíz del mensaje y puede faltar) |
SCROLL_TO_TOP | onScrollToTop() | ninguno |
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 | solo onEvent | eventData |
Comandos enviados
frame.send(eventType, eventData?) envía { eventType, eventData } (en JSON) al iframe. Espera onReady antes de enviar: FIRST solo escucha después de cargar. Los comandos que FIRST entiende:
eventType | eventData |
|---|---|
sportId, leagueId, eventId | { value: id } |
liveBetting, home | { value: true } |
betting-history, open-bets, expand-bet-slip | { value: boolean } |
bscode | { value: código } (carga un boleto compartido) |
shareBetslip | { url } (respuesta al shareBetslip recibido) |
Errores
| Código | Cuándo |
|---|---|
UNAUTHENTICATED | sin sesión (no se hace ningún request); para el visitante, usa la URL pública |
INVALID_ARGUMENT (400) | FIRST no habilitado para el operador (usa el code del envelope) |
UNAVAILABLE (503) | configuración de FIRST incompleta, servicio de sesión caído o configuración de sportsbook del servicio de apuestas no disponible |
VALIDATION_ERROR | launch_url no http(s) absoluta o expires_in_seconds no positivo |
Identifica por el código: isEnginexError(error, 'UNAVAILABLE').
Pruebas
La ruta mock GET /first/session (con sesión iniciada) devuelve https://first.mock.local/sportsbook?operatorToken=... con validez de 24 h y un token nuevo en cada llamada.