Esta versión (v0.7) todavía no se publicó en npm.
Ir al contenido

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:

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

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

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

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

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

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

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 del inicio de sesión no se hace ninguna llamada autenticada: createSession() sin sesión se rechaza con UNAUTHENTICATED sin request.
  • Después del inicio de sesión, llama a createSession() y cambia el src por la launchUrl. connectFirstFrame relee el origen del src en cada mensaje, así que el mismo frame sigue valiendo; FIRST se recarga y envía APP_READY de nuevo.
  • Trata la sportsbookUrl de la configuración como cualquier URL recibida: úsala solo si es http(s) absoluta y sin credenciales. Si tu configuración también trae config.widgetUrl, la app player se la pasa a FIRST en el parámetro api de la URL pública (url.searchParams.set('api', widgetUrl)), solo cuando es https.
  • La URL pública no lleva token de operador. No reutilices una launchUrl antigua 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)HandlerArgumento
APP_READYonReady()ninguno
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 (o height en la raíz del mensaje); solo números positivos
BUTTON_REDIRECTonRedirect(data){ link?: string } (el link viene en la raíz del mensaje y puede faltar)
SCROLL_TO_TOPonScrollToTop()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, messageToParentsolo onEventeventData

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:

eventTypeeventData
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ódigoCuándo
UNAUTHENTICATEDsin 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_ERRORlaunch_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.