# Operator Games API SDK

The **Operator Games API SDK** is a JavaScript/TypeScript library that provides operators with a **unified integration layer** for multiple game suppliers, starting with **Turbostars and OneTouch Originals**. With this SDK, you can have: 

* **A unified interface** by integrating one SDK for multiple game suppliers,
* **Automatic token validation** done with Hub88 backend,
* **Automatically select the correct supplier** based on game code received after a successful token validation,
* **Integrate games directly** without iframes (Shadow Mode),
* **Configuration management** by handling provider-specific configurations seamlessly.

As the SDK runs natively, it avoids iframe limitations, reduces overhead, and provides a smoother, mobile-friendly gaming experience.

***

## Integration Flow

The integration follows a simple two-step process:

{% @mermaid/diagram content="sequenceDiagram
participant OP as Casino Frontend
participant OS as Operator Backend<br/>(server)
participant H88 as Hub88 API
participant SDK as Operator Games API<br/>SDK
participant TP as Game Supplier<br/>(e.g., Turbostars or OneTouch)

```
Note over OP,TP: Step 1: Backend Authorization
OP->>OS: User launches a game
OS->>H88: POST /game/authorize<br/>with user & game details
Note right of H88: Same payload as /game/url<br/>but returns SDK initialization data
H88-->>OS: Authorisation response:<br/>• provider_token<br/>• provider_pid<br/>• launcher_base_url<br/>• provider_user<br/>• provider_currency_code
OS-->>OP: Return authorisation data

Note over OP,TP: Step 2: Frontend SDK Initialisation
OP->>SDK: Initialise SDK with:<br/>• provider_token<br/>• provider_pid <br/>• launcher_base_url
SDK->>H88: Validate token through launcher_base_url
H88-->>SDK: Token validation response<br/>with game_code and api_url
SDK->>SDK: Detect supplier from game_code<br/>(btsg_ prefix = Turbostars)
SDK->>TP: Initialise provider SDK<br/>with converted configuration
TP-->>SDK: Supplier is ready
SDK-->>OP: Game is loaded and ready" %}
```

***

## Authorisation

* **The operator backend** calls Hub88’s [`/game/authorize`](#step-1-authorise-game-session-backend) endpoint and returns initialisation data to the frontend. See [Step 1 for the endpoint details.](#step-1-authorise-game-session-backend-authorise-api)&#x20;
* **Hub88 API** validates tokens, resolves provider and game configuration, and delivers provider-specific data. See [Step 1 for the API call's response](#step-1-authorise-game-session-backend-authorise-api).&#x20;
* **Operator Games API SDK** initialises the correct provider SDK based on the game code prefix (e.g., `btsg_` → Turbostars). See [Step 2 for how to initalise the SDK](#step-2-initialise-sdk-client-frontend).&#x20;
* **Game supplier (provider SDK)** is initialised seamlessly in the player’s browser.&#x20;

***

## Integration Steps

{% stepper %}
{% step %}

### Step 1: Authorise Game Session (Backend) - **Authorise API**&#x20;

Your backend must call the Hub88 **Authorise API** `/game/authorize` to retrieve the initialisation payload.

**Authorise API Endpoint**

* **Staging**

{% code overflow="wrap" lineNumbers="true" %}

```json
POST https://api.server1.ih.testenv.io/operator/generic/v2/game/authorize
```

{% endcode %}

* **Production**:

{% code overflow="wrap" lineNumbers="true" %}

```json
POST https://api.hub88.io/operator/generic/v2/game/authorize
```

{% endcode %}

**Request Body**

{% code overflow="wrap" lineNumbers="true" %}

```javascript
{
  "user": "john12345", // Required
  "token": "f562a685-a160-4d17-876d-ab3363db331c", // Required
  "sub_partner_id": "my-casino-id",
  "platform": "GPL_DESKTOP", // Required
  "operator_id": 1, // Required
  "meta": {},
  "ip": "0.0.0.0",
  "lobby_url": "https://amazingcasino.com/lobby", // Required
  "lang": "en", // Required
  "game_code": "btsg_csgo", // Required: Turbostars games start with 'btsg_'
  "deposit_url": "https://amazingcasino.com/deposit",
  "currency": "EUR", // Required
  "game_currency": "EUR",
  "country": "EE" // Required
}
```

{% endcode %}

**Response**

{% code overflow="wrap" lineNumbers="true" %}

```javascript
{
  "provider_pid": "ta-hub88-stage",  // Required: Partner key for SDK
  "provider_user": "cg_147549",  // Optional: User identifier
  "provider_token": "9002CAA58FE78D1C460E40EEA75563A54A377F5C",  // Required: SDK token
  "provider_game": null,   // Optional: Game identifier
  "provider_currency_code": "USD", // Optional: Currency code
  "launcher_base_url": "https://launcher.server1.ih.testenv.io"  // Required: API base URL
}
```

{% endcode %}

Return this payload securely to your frontend.
{% endstep %}

{% step %}

### Step 2: Initialise SDK Client (Frontend)

Use the data from the authorisation request's response to initialise the Operator Games API SDK on your frontend.

**Installation via CDN**

{% hint style="success" %}
Currently the available version is 1.1.2 with the full CDN URL being \
<https://cdn.hub88.io/games-sdk/hub88-games-sdk-1.1.2.js>
{% endhint %}

{% code overflow="wrap" lineNumbers="true" %}

```html
<script src="https://cdn.hub88.io/games-sdk/hub88-games-sdk-1.1.2.js"></script>
```

{% endcode %}

**Basic Integration Example**

{% code overflow="wrap" lineNumbers="true" %}

```html
<!-- Container for the game -->
<div id="game-container"></div>

<!-- Include the SDK -->
<script src="https://cdn.hub88.io/games-sdk/hub88-games-sdk-<version>.js"></script>

<script>
async function launchGame() {
  try {
    // Get authorization data from your backend
    const authData = await fetch('/api/game/authorize', {
      method: 'POST',
      body: JSON.stringify({
        game_code: 'btsg_csgo',
        user: 'player123'
        // ... other parameters
      })
    }).then(r => r.json());

    // Initialize Hub88 Games SDK
    const gameInstance = await Hub88Games.init({
      // Required parameters (minimum needed)
      provider_token: authData.provider_token,
      provider_pid: authData.provider_pid,        // Maps to provider_pid
      launcher_base_url: authData.launcher_base_url,

      // Optional parameters
      containerId: 'game-container',
      lang: 'en',
      loginUrl: 'sendPostMessage',  // or your login URL
      depositUrl: 'sendPostMessage' // or your deposit URL
    });

    console.log('Game loaded successfully!');

  } catch (error) {
    console.error('Failed to load game:', error);
  }
}

// Launch the game
launchGame();
</script>
```

{% endcode %}

### **Advanced Configuration**

This example uses two types of optional parameters for the initialisation.&#x20;

1. **Optional parameters within the initialisation.** These parameters help to customise the experience depending on how you wish the player to experience the gameplay.&#x20;
2. **Advanced parameters defined in the `meta` object.** These parameters are supplier-specific and allow to further update how the game is displayed, including but not limited to, changing the styles, controlling URL routing, updating currencies, and much more.&#x20;
   1. See Turbostars' advanced options in the code sample below (starting from row 12).&#x20;
   2. See [OneTouch Originals' advanced options here](https://docs.hub88.io/developer-docs/operator-sdks/using-onetouch-originals-in-the-sdk#optional-parameters-for-meta-object).

{% code title="" overflow="wrap" lineNumbers="true" %}

```javascript
const gameInstance = await Hub88Games.init({
  // Required parameters
  provider_token: authData.provider_token,
  provider_pid: authData.provider_pid,
  launcher_base_url: authData.launcher_base_url,

  // Optional parameters
  game_code: 'btsg_csgo',           // Override game code if needed - NOT necessary since we get this information from the session related to the token.
  containerId: 'game-container',    // DOM container ID

  // Advanced options (provider-specific)
  meta: {
    loginUrl: 'sendPostMessage',      // Login handling method
    depositUrl: 'sendPostMessage',    // Deposit handling method
    lang: 'en',                       // Language preference
    allowToChangeParentStyles: true,  // Allow game to modify parent CSS
    disallowUrlChange: false,         // Control URL routing behavior
    lineFilter: 'sport',              // Filter content: 'sport', 'esport', or custom
    sub_partner_id: 'casino-section', // Sub-partner identification
    customStyles: 'https://cdn.example.com/game-styles.css'  // Custom styling
  }
});
```

{% endcode %}
{% endstep %}
{% endstepper %}

***

## SDK Methods and Lifecycle

| Method            | Description                                            |
| ----------------- | ------------------------------------------------------ |
| `isInitialized()` | Returns `true` if SDK is ready.                        |
| `getProvider()`   | Returns the detected provider (e.g., `turbostars`).    |
| `update(config)`  | Updates optional configuration (e.g., language, meta). |
| `destroy()`       | Cleans up resources and terminates the session.        |

#### Instance Methods

<pre class="language-javascript" data-title="Check if SDK is initialized" data-line-numbers><code class="lang-javascript"><strong>if (gameInstance.isInitialized()) {
</strong>  console.log('SDK is ready');
}
</code></pre>

{% code title="Get current provider" lineNumbers="true" %}

```javascript
const provider = gameInstance.getProvider(); // Returns: 'turbostars'
```

{% endcode %}

{% code title="Update configuration (optional parameters only)" lineNumbers="true" %}

```javascript
await gameInstance.update({
  lang: 'es',
  meta: {
    lineFilter: 'esport'
  }
});
```

{% endcode %}

{% code title="Clean up when done" overflow="wrap" lineNumbers="true" %}

```javascript
await gameInstance.destroy();
```

{% endcode %}

***

## Multi-Supplier Support

This SDK is built on a **multi-supplier architecture**, allowing operators to integrate with a wide range of game suppliers through a single SDK. Currently, the SDK supports two game suppliers - Turbostars and OneTouch Originals.&#x20;

We're adding new suppliers gradually without any need for you to change your integration. This ensures long-term scalability and compatibility as more providers are onboarded.

#### Turbostars Integration

{% hint style="success" %}
See how to incorporate [Turbostars Sportsbook modules in here](https://docs.hub88.io/developer-docs/operator-sdks/operator-games-api-sdk/turbostars-sportsbook-modules).&#x20;
{% endhint %}

Games with the prefix `btsg_` are automatically recognised and handled by the supplier **Turbostars**.

* **Supported Games**:\
  CS:GO, Dota 2, LoL, and other esports titles\
  \
  \&#xNAN;*Example:* The game\_code for Counter-Strike: Global Offensive would be displayed as  `game_code: "btsg_csgo"`
* **Features**: \
  Live betting, pre-match odds, multiple bet types

#### OneTouch Originals Integration

{% hint style="success" %}
See how to incorporate [OneTouch Originals here](https://docs.hub88.io/developer-docs/operator-sdks/operator-games-api-sdk/using-onetouch-originals-in-the-sdk).
{% endhint %}

Games with the prefix `orgn_` are automatically recognised and handled by the supplier **OneTouch Originals**.

* **Supported Games**:\
  dice, plinko, roulette, blackjack, baccarat, hilo. \
  \
  \&#xNAN;*Example:* `game_code: "orgn_originalplinko"`

***

## Error Handling

### Common Error Scenarios

| Error Code                  | Message                               | Description                                                                   | Recommended Action                                                                                 |
| --------------------------- | ------------------------------------- | ----------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| `INVALID_TOKEN`             | Token validation failed               | The provided token is invalid, expired, or not recognised by Hub88.           | Refresh or reissue the token and reattempt initialisation.                                         |
| `PROVIDER_NOT_FOUND`        | Game provider not supported           | The SDK could not detect or match the game’s provider (e.g., unknown prefix). | Verify the game code and ensure the provider is supported by the SDK.                              |
| `CONTAINER_NOT_FOUND`       | Game container missing                | The specified DOM container for the game does not exist or cannot be found.   | Ensure the container element (e.g. `#game-container`) is present in the DOM before initialisation. |
| `CONFIG_VALIDATION_FAILED`  | Invalid configuration                 | One or more configuration parameters are missing or invalid in the SDK setup. | Check all required parameters (`provider_token`, `provider_pid`, `launcher_base_url`).             |
| `UNKNOWN_ERROR` *(default)* | Initialisation failed (generic error) | A non-specific error occurred during SDK setup or communication.              | Review logs for details and confirm SDK configuration and network connectivity.                    |

{% code title="Error handling example" overflow="wrap" lineNumbers="true" %}

```javascript
try {
  const gameInstance = await Hub88Games.init(config);
} catch (error) {
  switch (error.code) {
    case 'INVALID_TOKEN':
      console.error('Token validation failed:', error.message);
      // Redirect to login or refresh token
      break;

    case 'PROVIDER_NOT_FOUND':
      console.error('Game provider not supported:', error.message);
      // Show unsupported game message
      break;

    case 'CONTAINER_NOT_FOUND':
      console.error('Game container missing:', error.message);
      // Ensure DOM container exists
      break;

    case 'CONFIG_VALIDATION_FAILED':
      console.error('Invalid configuration:', error.message);
      // Check required parameters
      break;

    default:
      console.error('Initialization failed:', error.message);
  }
}
```

{% endcode %}

### Validation Requirements

The SDK validates these required parameters:

* `provider_token` - Required, alphanumeric string 10–100 characters. Can't be empty or null.
* `provider_pid` - Required, non-empty string.
* `launch_base_url` - Required, must be a valid URL

### Security Considerations

1. **Follow the best practices of Server-Side Authorisation.** Always call[ `/game/authorize` ](#step-1-authorise-game-session-backend-authorise-api)from your backend, never expose operator credentials to the frontend.
2. **Do not expose operator credentials.**
3. **Generate fresh tokens for each new session.**

***

## Additional links

* Learn more about Turbostars Shadow mode and troubleshoot any issues with their API in <https://docs.turbostars.gg/#/frontend/about_shadow_mode?id=about-shadow-mode>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.hub88.io/developer-docs/operator-sdks/operator-games-api-sdk.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.