Data Integration Requirements

Intended Audience

This article is for the technical team responsible for configuring your event data integration. It covers the following:

• The events required to use Xtremepush Intelligence

• How event categories map to the Intelligence model

• How to prepare before the data mapping stage begins

For the onboarding process and timeline, see the Setup Overview. For integration mechanics, see the Choosing your integration method section below.

What Intelligence needs from your data

Intelligence classifies each incoming event into two things:

1. Category: The business domain of the event (casino, sports, bingo, deposit, and so on)

2. Four payload extracts: The specific values needed to compute metrics: monetary amount, transaction key, real-money vs. bonus indicator, and item dimension

The category is determined during the data mapping stage based on your event names and structure. The four extracts are fields you need to ensure are present in your event payloads.

Supported event categories

Xtremepush maps your existing events to the categories below during the data mapping stage.

Categories requiring a debit and credit pair (casino, sports, bingo) need both the wager event and the payout or settlement event to be sent, each with the same transaction key, for GGR calculation to work.

Sub-vertical classification

Casino is a single category covering multiple game types. There is no separate category for live dealer, virtual sports, or table games, these are all sent as casino events. Use the item field (the game name or game code) to carry the sub-vertical detail.

This means a single casino event stream covers your full casino product. The item field is what powers per-game breakdowns in the pre-built datasets.

The four required payload extracts

For Intelligence to compute GGR, deposit metrics, and other aggregates, four pieces of information must be present inside the event's value object. The field names are client-specific, Intelligence maps to whatever your system uses, but all four must be present for full metric coverage.

1. Monetary value

The stake or payout amount as a numeric value.

• Casino / sports / bingo debit events: the wager or stake amount

• Casino / sports / bingo credit events: the payout or settlement amount

• Deposits: the deposit amount

• Withdrawals: the withdrawal amount

2. Transaction key

A unique identifier that links a wager to its corresponding payout. The same key must appear on both the debit event (bet placed) and the credit event (payout or settlement). This is what makes GGR calculation possible.

• For casino: typically a round ID, game session ID, or bet ID

• For sports: the bet reference or settlement ID

• For bingo: the game activity ID or ticket ID

• For deposits and withdrawals: the transaction or ledger ID

If your wager and payout events use different identifiers, flag this during the data mapping stage, there are options for handling it.

3. Real-money vs. bonus distinction

Intelligence tracks real-money and bonus play separately. Without this, GGR will be overstated by bonus wagers and cannot be corrected retrospectively.

There is no required field name for this, Intelligence maps to whatever mechanism your platform already uses. The common approaches are:

• A boolean or status field on the event: for example, a field that indicates whether the wager used real funds or a bonus. If this field already exists in your data under any name, the data team will map to it.

• Separate event names: if your platform fires different event names for real-money vs. bonus activity (for example, a real wager and a free bet as distinct event types), these can be mapped independently.

• A type or source field with distinguishable values: for example, a field that indicates payment method or wallet type, where bonus wagers have a consistently identifiable value.

If your data does not currently distinguish real-money from bonus activity in any of these ways, you will need to add an indicator before the integration goes live. Any consistent, queryable field works, the specific name does not matter. Flag this during the data mapping stage and the team will advise on the simplest approach for your platform.

4. Item dimension

The game name, sport name, or bingo room that the event relates to. This field is optional in the sense that omitting it will not break the core metrics, but it is required if you want:

• Per-game casino analytics in the pre-built datasets

• Per-sport betting breakdowns

• Per-room bingo analytics

Event envelope

Both the REST API and Kafka integration use the same structure. The value object carries all event-specific properties, Intelligence reads from whichever fields you use inside it.

The field names inside value are illustrative, your system will use whatever names already exist in your payload. The data mapping stage establishes how each field maps to Intelligence.

Example: casino wager event

{
  "event": "casino_bet",
  "user_id": "player_12345",
  "timestamp": "2024-06-01 14:32:00.000",
  "value": {
    "stake": 5.00,
    "round_id": "rnd_abc789",
    "game_name": "Starburst",
    "is_real_money": true
  }
}

stake is the monetary value, round_id is the transaction key, game_name is the item dimension, is_real_money is the bonus indicator, using this client's own field names.

Example: sports bet event

{
  "event": "sports_wager",
  "user_id": "player_12345",
  "timestamp": "2024-06-01 14:35:00.000",
  "value": {
    "wager_amount": 20.00,
    "bet_id": "bet_xyz456",
    "sport": "Football",
    "is_free_bet": false
  }
}

wager_amount is the monetary value, bet_id is the transaction key, sport is the item dimension, is_free_bet is the bonus indicator.

Bonus event structure

Bonus events support a sub-category to indicate which vertical the bonus is attached to. This enables per-vertical bonus attribution in your analytics.

Sub-categories are configured during the data mapping stage and do not require changes to your event schema.

Non-transactional events

The following event types can be sent and will flow into the Intelligence event store, but do not feed into computed player attributes (GGR, deposits, wagering metrics):

These events are valid and useful for campaign targeting via raw event conditions, but they will not appear in your GGR, deposit, or betting totals.

Choosing your integration method

The REST API and Kafka integrations use the same event envelope structure, the value object content is identical regardless of which transport you use.

Pre-integration checklist

Complete the data mapping form provided by your account team before or during your integration. The form covers the questions below. Having clear answers speeds up the data mapping stage significantly.

Event coverage

• Which event names in your system correspond to each Intelligence category (casino bet, sports bet, bingo stake, deposit, withdrawal, bonus awarded, bonus used)?

• Do you send separate events for wager placement and payout/settlement, or a single event?

• Do you have bingo as a product? If so, what event names cover bingo stakes and payouts?

Payload content

• What field name holds the monetary value (stake amount, payout amount, deposit amount)?

• What field name is your transaction key, the ID that appears on both the wager and the payout?

• How do you distinguish real-money from bonus events, a flag field, separate event names, or another approach?

• What field carries the game name, sport name, or bingo room?

Data availability

• Is historical event data available? If so, from what date?

• Are there any known gaps in historical data (platform migrations, schema changes)?