Frontend Integration

The final piece of the ThrillPots integration puzzle is the frontend integration. The frontend is responsible for displaying the Jackpot Ticker widget, showing players what the value of the various pots within the Jackpot are, the opt-in widget, allowing players to opt-in or opt-out of participation in the jackpot and so on.

The ThrillConnect Service has been specifically developed to provide an API and event stream over WebSockets to frontend clients to be able to interact with the ThrillPots system.

Integration Options

When integrating the frontend, there are two options that you can take:

Use the existing libraries/components that ThrillTech has built to ease the effort of frontend integration:
- ThrillConnect JS Client
- Animation Driver
Develop your own integration with ThrillConnect and your own animation layer for the win animations

The sections below will detail the low level integration approach to help you understand how things work. You can then decide which of the options mentioned above you wish to take.

Sequence Diagram for the frontend to ThrillConnect integration

Integration Flow in detail

Fetching a Jackpot's details

One of the first things your frontend will most likely need to do is to retrieve jackpot details for your jackpot widget to display.

If you have followed the section on settings up the AIO container, you would have created a Source called sitewide-casino.

If you haven't gone through the process of setting up a source, we suggest that you review and understand sources and how they are used before continuing

To retrieve the jackpot for the sitewide-casino source, you will need to call:

GET /v1/thrillpots/instances/source/:source_id/brand/:brand_id?player_id=:player_id

replacing the :source_id and :brand_id values with the appropriate values that have been configured. If you used the default values from the Postman collection, you can use sitewide-casino for the source_id and thrilltech:brand1 for the brand_id.

If the player is already logged in, you can also pass the ID of the player via the query parameter player_id. Doing so will ensure that the player's opt-in status is returned in the jackpot instance information.

Establishing a WebSocket connection

In order to receive ThrillPots events and be able to opt players in or out of the jackpot, you will need to establish a websocket connection.

Once a player is logged into an operator's site, you can establish a WebSocket connection with ThrillConnect, passing in the player's session token.

NOTE

WebSocket connections are protected and can only be established by logged in players to prevent unauthorized and potentially dangerous abuse by attackers. Requiring a player a valid player session token in order to establish a WebSocket connection is a security-driven decision

To establish a WebSocket connection with ThrillConnect, open a WebSocket to:

/v1/events/{operator_id}/{brand_id}?token=PLAYER_TOKEN&currency=PLAYER_CURRENCY

ThrillConnect will authenticate the token (the Player session token) from the query parameters with the operator's platform via ThrillGate. If the token is valid, the websocket connection will be established. If the token is invalid, the connection will receive a 403 FORBIDDEN error.

Subscribing to ThrillPots events

Once you have successfully established a WebSocket connection, you can now subscribe to ThrillPots events. This is done by sending a subscription request via the WebSocket to ThrillConnect. See below for the SubscribeRequest message that should be sent to subscribe to all ThrillPots events:

{
    "SubscribeRequest": {
        "events": [{
            "source": "thrillpots",
            "event_type": "*"
        }]
    }
}

If you would like to subscribe to only certain events, you can do so by explicitly specifying the events by source one-by-one.

ThrillPots currently publishes the folliowing event types:

JackpotUpdateEvent
WinEvent
RaffleWinEvent
OptInEvent

For more information about the structure of each of these events, see ThrillPots Event Structures

Player Opt-in / Opt-out

To opt a player in or out of a jackpot, you must send a PlayerOptInRequest message via the WebSocket connection.

Below are a few examples of opting a player in and out of a jackpot instance (please note, you will need to have the jackpot instance ID):

Opting in

{
    "PlayerOptInRequest": {
        "instance_id": "8dcc9f5a-f1c5-466f-83e9-928277d8bfb7",
        "player_id": "player_00001",
        "brand_id": "thrilltech:brand1",
        "player_country": "MT",
        "opt_in": true
    }
}

Opting in with a preferred contribution value of 0.20

{
    "PlayerOptInRequest": {
        "instance_id": "8dcc9f5a-f1c5-466f-83e9-928277d8bfb7",
        "player_id": "player_00001",
        "brand_id": "thrilltech:brand1",
        "player_country": "MT",
        "opt_in": true,
        "contribution_value": 0.2
    }
}

Opting out of a Jackpot

{
    "PlayerOptInRequest": {
        "instance_id": "8dcc9f5a-f1c5-466f-83e9-928277d8bfb7",
        "player_id": "player_00001",
        "brand_id": "thrilltech:brand1",
        "player_country": "MT",
        "opt_in": false
    }
}

Retrieving Exchange Rates

You may need to convert the values of a jackpot instance from the Jackpot currency to a player's currency. To help facilitate this, ThrillConnect exposes a currency endpoint which allows you to fetch the exchange rates used by ThrillPots.

To retrieve the 202408-1 exchange rates, you can call:

GET /v1/currencies

Retrieving a player's raffle ticket count

If player's are contributing to a Raffle jackpot, you may want to show the player how many tickets they have earned so far in the raffle. You can retrieve the player's current ticket count by requesting it via the WebSocket connection:

To retrieve a player's ticket count, send a PlayerRaffleTicketsRequest message:

{
    "player_id": String,
    "instance_id": String,
    "brand_id": String
}

The instance_id is the instance ID of the Raffle jackpot, and the brand_id is in the format operator_id:brand_id.

If the request can be serviced, you should received a PlayerRaffleTicketsResponse message back:

{
    "msg_type": "Message",
    "source": "thrillpots",
    "msg_name": "PlayerRaffleTicketResponse",
    "operator_id": "OPERATOR_ID",
    "brand_id": "BRAND_ID",
    "player_id": "PLAYER_ID",
    "data": {
        "ticket_count": 4
    },
    "timestamp": 1711452762485
}

If there was an error processing the request, you will receive an Error message in response which will contain the message name that errored, as well as any relevant error details. For example:

{
    "msg_type": "Error",
    "source": "thrillpots",
    "msg_name": "PlayerRaffleTicketRequest",
    "operator_id": "OPERATOR_ID",
    "brand_id": "BRAND_ID",
    "player_id": "PLAYER_ID",
    "data": {
        "status_code": 404,
        "code": "",
        "message": "Error 404 Not Found from http://localhost:8084/instances/raffle/e0dee1ae-6231-458a-ad6d-4dc0c941e5c3/tickets/player_00001/brand/thrilltech:brand1"
    },
    "timestamp": 1711452757807
}

In this case, the request Jackpot instance ID could not be found.

ThrillTech Technology & Integration Guide (SaaS)