Cassino
Carregando a demo interativa…
A demo acima usa createIgaming(enginex) sobre um cliente com createMockFetch e as rotas de @getenginex/sdk-igaming/testing: nenhuma chamada sai para a rede. O lobby é público (categorias, provedores, filtros e páginas de listGames); Play e Demo exigem login. A gameUrl devolvida por launchGame carrega o token da sessão de jogo: a demo não navega e mostra a URL com o token mascarado, na tela e no painel Under the hood. Os cenários mostram SELF_EXCLUDED no modo real (o modo demo continua abrindo) e PROVIDER_ERROR no catálogo.
O namespace casino de @getenginex/sdk-igaming cobre o lobby (catálogo, categorias e provedores), a abertura de jogos e o histórico do jogador. O catálogo é público: funciona sem login e não manda a sessão, mesmo com o jogador logado. Abrir jogo, sessões, histórico e o ranking de ganhadores exigem login (enginex.auth.login). Em testes, withIgamingRoutes já responde a todas estas rotas (veja Testes).
import { createEnginexClient } from '@getenginex/sdk'
import { createIgaming } from '@getenginex/sdk-igaming'
export const enginex = createEnginexClient({ locale: 'pt-BR' })
export const igaming = createIgaming(enginex)Lobby: jogos, categorias e provedores
const [categories, providers] = await Promise.all([
igaming.casino.listCategories(), // [{ slug: 'slots', name: 'Slots', icon, gameCount, priority }]
igaming.casino.listProviders(), // [{ id: 'Pragmatic Play', name: 'Pragmatic Play', gameCount }]
])
const page = await igaming.casino.listGames({
category: 'slots', // slug from listCategories
provider: 'Pragmatic Play', // id from listProviders (opaque: pass it as received)
search: 'olympus', // game name, up to 100 characters
sort: 'popular', // 'popular' | 'new' | 'az'
page: 1,
perPage: 24, // 1 to 100; default 20
})
page.items // Game[]: id, name, thumbnail, isNew, isPopular, isLive, demoAvailable, rtp...
page.totalPageslistGames devolve uma página (items, page, perPage, totalPages, totalItems). Para validar favoritos ou recentes salvos no app, passe os ids em ids (até 100): jogos que saíram do catálogo simplesmente não voltam.
const favorites = await igaming.casino.listGames({ ids: savedIds, perPage: 100 })Um jogo específico: igaming.casino.getGame({ gameId }) (GAME_NOT_FOUND se não existir).
Disponibilidade do cassino
Manutenção, troca de provedor, indisponibilidade temporária e operador sem cassino não são erros: o gateway responde 200 e informa o motivo num campo availability ao lado da lista de jogos, que esta versão do SDK ainda não expõe. Nesses casos a lista pode vir vazia, sem erro — mostre um estado vazio genérico. UNAVAILABLE/PROVIDER_ERROR (503) só chegam quando a própria chamada ao serviço de cassino falha.
Abrir um jogo
launchGame cria a sessão de jogo (encerrando a anterior) e devolve a URL e como o provedor exige que ela seja aberta, em launchTarget: iframe (embutida na página), redirect (navegar a aba atual) ou new_tab. Alguns provedores se recusam a rodar dentro de um iframe, então sempre decida por ele. launchTarget é uma união aberta: trate um valor que o SDK ainda não conhece como new_tab. O launch também devolve providerCode e, quando o provedor informa, expiresAt (abra o jogo antes dele):
import { isEnginexError } from '@getenginex/sdk'
try {
const launch = await igaming.casino.launchGame({
gameId: game.id,
mode: 'real', // or 'demo', if game.demoAvailable
isMobile: window.matchMedia('(max-width: 768px)').matches,
})
// Open the game the way its provider requires
if (launch.launchTarget === 'iframe') iframe.src = launch.gameUrl
else if (launch.launchTarget === 'redirect') window.location.assign(launch.gameUrl)
else {
// 'new_tab', or a target the SDK does not know yet. Opened after an await, the tab may be blocked as
// a popup (window.open returns null): fall back to the current tab.
const tab = window.open(launch.gameUrl, '_blank')
if (tab) tab.opener = null
else window.location.assign(launch.gameUrl)
}
} catch (e) {
if (isEnginexError(e, 'SELF_EXCLUDED') || isEnginexError(e, 'COOLING_OFF')) showResponsibleGamingNotice()
else if (isEnginexError(e, 'GAME_NOT_FOUND')) showGameUnavailable()
else throw e
}- Idioma: o gateway usa o
languagedo input ou, sem ele, oAccept-Languagedo request — que o SDK preenche com olocaledo cliente (createEnginexClient({ locale })ouenginex.setLocale()). - Volta ao lobby: sem
returnUrl, o gateway usa oOrigindo request, que o browser sempre manda. Em chamadas de servidor (SSR, Node), passereturnUrlcom uma URL absoluta. - Bloqueio de popups: os navegadores só liberam
window.opendurante o próprio clique, e o exemplo o chama depois de esperar olaunchGame, então alguns navegadores (o Safari em especial) bloqueiam a nova aba; o exemplo cai então na aba atual. Para ter sempre uma aba de verdade, abra-a no handler do clique antes do launch (const tab = window.open('about:blank', '_blank')) e depois façatab.location.href = launch.gameUrlparanew_tab, outab.close()paraiframe/redirect. O custo é uma aba em branco que abre, por um instante, para todo jogo. - URL relativa: conforme o provedor,
gameUrlpode vir relativa ao gateway; nesse caso, resolva contra a origem do gateway (new URL(gameUrl, gatewayOrigin)). - Não é idempotente: cada chamada abre uma sessão nova (e encerra a anterior). Em erro de rede, chamar de novo é seguro.
- Demo também exige login: a rota é protegida; para visitantes, mostre o catálogo e peça login ao abrir o jogo.
A URL do jogo é um segredo
gameUrl carrega o token da sessão de jogo do jogador: quem tiver a URL joga com o saldo dele. O SDK a entrega só no retorno de launchGame — nenhum hook (onRequest, onResponse, onError) nem onValidationIssue recebe a URL, e a resposta é validada sempre em modo estrito (uma resposta fora do formato vira VALIDATION_ERROR, sem os valores). Não registre a URL em logs, analytics, Sentry nem em storage; use-a só para abrir o jogo.
Sessões, histórico e ganhadores
const sessions = await igaming.casino.listSessions({ perPage: 10 })
sessions.items[0] // { id, gameId, gameName, provider, startTime, totalBet, totalWin, status: 'active' | 'ended' }
const history = await igaming.casino.getHistory({ page: 1, perPage: 20 })
history.items[0] // { roundId, type: 'bet' | 'win' | 'refund' | 'jackpot' | 'free_spin' | 'reversal', amount, currency, ... }
const winners = await igaming.casino.getBiggestWinners({ limit: 10, days: 7 })
winners[0] // { player: 'Jo***', amount, currency, gameName, wonAt }Valores são sempre unidades menores (centavos no BRL; veja Dinheiro). No histórico e no ranking o gateway envia o valor como texto (inteiro de 64 bits); o SDK converte para number e recusa com VALIDATION_ERROR um valor que não caiba com precisão. totalBet/totalWin das sessões estão na moeda do operador. Os status/type chegam em minúsculas, sem o prefixo do protobuf; um valor novo passa adiante no mesmo formato — trate o caso padrão.
O ranking mostra só o nome mascarado pelo gateway (Jo***): o id e o nome completo do jogador nunca chegam ao app.
Erros
| Código | Quando |
|---|---|
GAME_NOT_FOUND (404) | getGame/launchGame com um id que não existe no catálogo |
FAILED_PRECONDITION (422) | launchGame de um jogo inativo |
SELF_EXCLUDED (422), COOLING_OFF (500), ACCOUNT_BLOCKED (500) | launchGame (modo real) de um jogador com restrição de jogo responsável |
INVALID_ARGUMENT (400) | listGames com search acima de 100 caracteres ou mais de 100 ids |
UNAVAILABLE (503) | a chamada ao serviço de cassino falhou, ou sem como verificar as restrições |
PROVIDER_ERROR (503), CASINO_UNAVAILABLE (500) | códigos definidos no enginex-commons para falha do provedor/cassino: trate como indisponível |
UNAUTHENTICATED (401) | métodos que exigem login, sem sessão |
Identifique pelo código, não pelo status
COOLING_OFF, ACCOUNT_BLOCKED e CASINO_UNAVAILABLE ainda não têm um status próprio no gateway e chegam com HTTP 500; só PROVIDER_ERROR é mapeado para 503. O código vem certo: use sempre isEnginexError(error, code) (veja Erros), nunca error.status.
Testes
import { createEnginexClient } from '@getenginex/sdk'
import { createMockFetch, fail } from '@getenginex/sdk/testing'
import { createIgaming } from '@getenginex/sdk-igaming'
import { withIgamingRoutes } from '@getenginex/sdk-igaming/testing'
const enginex = createEnginexClient({
baseUrl: 'https://gateway.test', // in Node: absolute baseUrl + tenantHost (optional in the browser)
tenantHost: 'casino.test',
fetch: createMockFetch(withIgamingRoutes()),
})
const igaming = createIgaming(enginex)
await igaming.casino.listGames({ category: 'live' }) // fixed catalog: 7 games, 3 categories, 3 providers
await enginex.auth.login({ email: 'ana@exemplo.com', password: 'Senha@123' })
const { gameUrl } = await igaming.casino.launchGame({ gameId: 'mock-game-1' })
// https://games.mock.local/play/mock-game-1?token=mock-launch-token-1&lang=...O mock guarda estado por instância: abrir um jogo cria uma sessão active e encerra a anterior, e um id desconhecido devolve GAME_NOT_FOUND. Para simular erros, sobrescreva a rota: withIgamingRoutes({ routes: { 'POST /api/v1/games/:gameId/launch': () => fail(422, 'SELF_EXCLUDED') } }).