Gamification Balance Update Event

Info

Draft Documentation - This section is currently under review and may be subject to changes.

The gamification balance update event is sent via SSE when a player’s gamification coin balance changes. This provides real-time updates for balance changes due to earning, redeeming, or other gamification-related activities.

Event Type

event_type: gamification_balance_update

Event Structure

{
  "brand_id": 1001,
  "player_id": 12345,
  "event_type": "gamification_balance_update",
  "event_data": {
    "balance": 1500,
    "total_received": 5000,
    "total_redeemed": 3500
  }
}

Fields

Base Event Fields

Field	Type	Description
brand_id	int	The casino brand identifier.
player_id	int	The player identifier.
event_type	string	Always “gamification_balance_update” for this event.
event_data	object	Balance update data (see below).

Event Data Fields

Field	Type	Description
balance	decimal	Current gamification coin balance after the update.
total_received	decimal	Total gamification coins received by the player (lifetime).
total_redeemed	decimal	Total gamification coins redeemed by the player (lifetime).

Event Examples

Example 1: Balance Update After Earning Coins

This event is sent when a player earns gamification coins (e.g., from gameplay activity).

{
  "brand_id": 1001,
  "player_id": 12345,
  "event_type": "gamification_balance_update",
  "event_data": {
    "balance": 2500,
    "total_received": 10000,
    "total_redeemed": 7500
  }
}

Example 2: Balance Update After Redemption

This event is sent when a player redeems gamification coins for rewards.

{
  "brand_id": 1001,
  "player_id": 12345,
  "event_type": "gamification_balance_update",
  "event_data": {
    "balance": 500,
    "total_received": 10000,
    "total_redeemed": 9500
  }
}

Example 3: New Player with Zero Redemptions

This event shows a player who has earned coins but not yet redeemed any.

{
  "brand_id": 1001,
  "player_id": 12345,
  "event_type": "gamification_balance_update",
  "event_data": {
    "balance": 750,
    "total_received": 750,
    "total_redeemed": 0
  }
}

Client Implementation

JavaScript Example

const eventSource = new EventSource('/gateway/sse/1001/stream', {
  headers: {
    'x-auth-token': playerToken
  }
});

eventSource.onmessage = (event) => {
  const data = JSON.parse(event.data);

  // Filter for gamification balance update events
  if (data.event_type === 'gamification_balance_update') {
    const balanceData = data.event_data;
    updateGamificationBalanceUI(balanceData);
  }
};

function updateGamificationBalanceUI(balanceData) {
  // Update the displayed balance
  document.getElementById('coin-balance').textContent =
    formatNumber(balanceData.balance);

  // Optionally update lifetime stats
  document.getElementById('total-earned').textContent =
    formatNumber(balanceData.total_received);
  document.getElementById('total-redeemed').textContent =
    formatNumber(balanceData.total_redeemed);

  // Show visual feedback for balance change
  highlightBalanceChange();
}

function formatNumber(value) {
  return new Intl.NumberFormat('en-US').format(value);
}

Use Cases

This event is triggered in the following scenarios:

Scenario	Description
Coin Earning	Player earns coins from gameplay or activities
Coin Redemption	Player redeems coins for rewards or bonuses
Admin Adjustment	Manual balance adjustment by operator
Promotional Credit	Promotional coins added to player’s balance
Expiration	Coins expired due to inactivity or time limits

Best Practices

Real-time UI Updates: Update the gamification balance display immediately upon receiving this event
Animation: Consider adding visual feedback (e.g., animation, color change) when the balance updates
Graceful Degradation: If SSE is unavailable, fall back to polling the balance endpoint
Number Handling: Balance values are returned as rounded numbers but should be treated as decimals for storage and calculations