Getting Started with hizi engine SDK

The hizi engine SDK (@hizi.io/engine-sdk) helps your game frontend communicate with a running hizi engine. This page shows how to install the SDK. It then shows your first API calls.

Installation

The SDK is available in the public npm registry. Install it like any other npm package:

npm

npm install @hizi.io/engine-sdk

pnpm

pnpm add @hizi.io/engine-sdk

yarn

yarn add @hizi.io/engine-sdk

Quick Start

Prerequisites

Before you run this walkthrough, get two things ready. First, get access credentials to the hizi Backoffice. Use these credentials to launch the game and to get the login/token URL parameters. Second, get a frontend game client to embed the game in. See What You Need below.

Four core calls drive the whole game lifecycle: login, loadConfig, placeBet, and collect. The annotated walkthrough below shows the calls in order. It also shows two follow-up patterns: continuing a multi-step round, and collecting winnings. These patterns use repeated placeBet and collect calls:

import { login, loadConfig, placeBet, collect } from '@hizi.io/engine-sdk';

// 1. Get launch parameters from the URL
const loginURL = new URLSearchParams(window.location.search).get('login');
const launchToken = new URLSearchParams(window.location.search).get('token');

// 2. Login - exchange launch token for session token
const loginResponse = await login({ loginURL, launchToken });
if (!loginResponse.success) throw new Error('Login failed');

const { token, backendURL, gameSettings } = loginResponse.result;

// Apply operator platform settings (stake limits, enabled features, UI rules).
// The engine does not re-enforce these - your frontend must honour them.
if (gameSettings) {
  applyStakeLimits(gameSettings.minStake, gameSettings.maxStake, gameSettings.customStakes);
  ui.setAutoplayEnabled(gameSettings.autoplayEnabled);
  ui.setGambleEnabled(gameSettings.gambleEnabled);
  // …see /sdk/endpoints#login for the full list
}

// 3. Load game configuration
const configResponse = await loadConfig({ backendURL, token });
if (!configResponse.success) throw new Error('Config load failed');

const config = configResponse.result.config;
console.log('Stakes:', config.stakes); // e.g. [10, 20, 50, 100]
console.log('RTP:', config.rtp); // e.g. 95

// 4. Place a bet
const stake = config.stakes[0];
const betResponse = await placeBet({ backendURL, token, stake, config });
if (!betResponse.success) throw new Error('Bet failed');

const gameResult = betResponse.result.result;
console.log('Scenario data:', gameResult.scenario); // your game-specific data
console.log('Total win:', gameResult.totalWin); // win multiplier

// 5. Handle multi-step rounds
if (gameResult.engineData.inProgress) {
  // Call placeBet again to continue
  const nextResponse = await placeBet({ backendURL, token, config });
}

// 6. Collect winnings when available (games with wager features)
if (gameResult.engineData.canCollect) {
  const collectResponse = await collect({ backendURL, token });
}

TIP

Every response has a success boolean. Always check it before accessing result. See Error Handling for details.

What You Need

• Access credentials to hizi Backoffice
• A frontend game client (HTML5, React, Unity, etc.)
• TypeScript recommended for type safety