Skip to content
Golden WhaleGolden WhaleFoundation

Foundation event

The foundation event is the top-level object emitted per player. The table below lists its root fields; nested object types are documented in the sections that follow, and the links in the Type column jump to them.

Root object

Section titled “Root object”
FieldTypeDescription
playerrequiredobject
triggeroptionalscheduledsessionWhat produced this event: 'scheduled' (batch run) or 'session' (real-time). All predictions in one event share this trigger.
valueoptionalvaluePrediction
churnRiskoptionalchurnRiskPrediction
sessionChurnRiskoptionalsessionChurnRiskPrediction
incentiveUsageoptionalincentiveUsagePrediction
incentiveGuidanceoptionalincentiveGuidancePrediction
reactivationPotentialoptionalreactivationPotentialPrediction
incentiveRecommendationsoptionalarray of incentiveRecommendationmax 3 items
favoriteGameCategoriesoptionalarray of favoriteGameCategorymax 3 items
recommendedGamesoptionalarray of recommendedGamemax 3 items

Kafka headers

Section titled “Kafka headers”

Events delivered over Kafka carry a trigger message header with the same value as the root trigger field, so consumers can route or filter without parsing the payload.

Header Value
trigger scheduled (batch run) or session (real-time), UTF-8

Player

Section titled “Player”
FieldTypeDescription
idrequiredstring
cohortrequirednumber
grouprequiredTargetControl
metadataoptionalobjectFree-form, customer-specific metadata. Arbitrary key/value pairs not validated by the schema (e.g. siteId, brand, region). Lets customers attach bespoke data without changing the schema.

valuePrediction

Section titled “valuePrediction”
FieldTypeDescription
currentrequiredvaluePredictionEntry
previousoptionalvaluePredictionEntry

valuePredictionEntry

Section titled “valuePredictionEntry”
FieldTypeDescription
scorerequirednumberValue Score
sequencerequirednumbermin 1 / max 4A numeric representation of the player based on the value score
segmentrequired1. Low2. Core3. High4. VIPThe segment name of the player based on the value score
daterequiredstringISO8601 date-time

churnRiskPrediction

Section titled “churnRiskPrediction”
FieldTypeDescription
currentrequiredchurnRiskPredictionEntry
previousoptionalchurnRiskPredictionEntry

churnRiskPredictionEntry

Section titled “churnRiskPredictionEntry”
FieldTypeDescription
scorerequirednumbermin 0 / max 1Churn Risk Score
sequencerequirednumbermin 1 / max 4A numeric representation of the player based on the churn risk score
segmentrequired1. Low2. Medium3. High4. DormantThe segment name of the player based on the Risk Score
daterequiredstringISO8601 date-time

sessionChurnRiskPrediction

Section titled “sessionChurnRiskPrediction”
FieldTypeDescription
currentrequiredsessionChurnRiskPredictionEntry
previousoptionalsessionChurnRiskPredictionEntry

sessionChurnRiskPredictionEntry

Section titled “sessionChurnRiskPredictionEntry”
FieldTypeDescription
scorerequirednumbermin 0 / max 1Session Churn Risk Score
sequencerequirednumbermin 1 / max 4A numeric representation of the player based on the churn risk score
segmentrequired1. Low2. Medium3. High4. DormantThe segment name of the player based on the Risk Score
daterequiredstringISO8601 date-time

incentiveUsagePrediction

Section titled “incentiveUsagePrediction”
FieldTypeDescription
currentrequiredincentiveUsagePredictionEntry
previousoptionalincentiveUsagePredictionEntry

incentiveUsagePredictionEntry

Section titled “incentiveUsagePredictionEntry”
FieldTypeDescription
scorerequirednumberIncentive Usage Score
sequencerequirednumbermin 1 / max 4A numeric representation of the player based on the churn risk score
segmentrequired0. No bonus usage1. Normal bonus usage2. Increased bonus usage3. Bonus abuserThe segment name of the player based on the incentive usage score
daterequiredstringISO8601 date-time

incentiveGuidancePrediction

Section titled “incentiveGuidancePrediction”
FieldTypeDescription
currentrequiredincentiveGuidancePredictionEntry
previousoptionalincentiveGuidancePredictionEntry

incentiveGuidancePredictionEntry

Section titled “incentiveGuidancePredictionEntry”
FieldTypeDescription
scorerequirednumberIncentive Guidance Score
sequencerequirednumbermin 1 / max 4A numeric representation of the recommended incentive posture
segmentrequired1. Increase Incentives2. Continue Incentives3. Limit Incentives4. Avoid IncentivesRecommended incentive posture for the player
daterequiredstringISO8601 date-time

reactivationPotentialPrediction

Section titled “reactivationPotentialPrediction”
FieldTypeDescription
currentrequiredreactivationPotentialPredictionEntry
previousoptionalreactivationPotentialPredictionEntry

reactivationPotentialPredictionEntry

Section titled “reactivationPotentialPredictionEntry”
FieldTypeDescription
scorerequirednumbermin 0 / max 1Reactivation Potential Score
sequencerequirednumbermin 1 / max 3A numeric representation of the player's reactivation potential
segmentrequired1. Low Potential2. Medium Potential3. High PotentialThe segment name of the player's reactivation potential
daterequiredstringISO8601 date-time

incentiveRecommendation

Section titled “incentiveRecommendation”
FieldTypeDescription
recommendationIdrequiredstringUnique identifier for this recommendation emission
rankrequirednumber1-based rank of the recommendation for the player
scorerequirednumberScore
incentiveIdrequiredstringIdentifier of the recommended incentive type
incentiveNamerequiredstringIncentive Name
amountrequirednumberAmount
triggerIdoptionalstringIdentifier of the trigger this recommendation came from

favoriteGameCategory

Section titled “favoriteGameCategory”
FieldTypeDescription
rankrequirednumber
scorerequirednumber
categoryIdrequiredstring
categoryNamerequiredstring

recommendedGame

Section titled “recommendedGame”
FieldTypeDescription
rankrequirednumber
scorerequirednumber
gameIdrequiredstring
gameNamerequiredstring
categoryIdrequiredstring
categoryNamerequiredstring

Example payload

Section titled “Example payload”

The same event as JSON and as a single flattened CSV row. model_dump_csv() produces the CSV form: nested objects become _-joined snake_case columns, bounded lists widen into 1-based indexed columns (incentive_recommendations_1_score, capped at three by maxItems), and unbounded values — free-form metadata — stay a single JSON-text column. The column set comes from the model, not the event, so every row carries every column and absent fields are simply empty.

Download this example as CSV
{
  "player": {
    "id": "PLAYER-ID-AS-GUID-OR-NUMERIC-123",
    "cohort": 1,
    "group": "Target",
    "metadata": {
      "siteId": 123,
      "brand": "golden-whale-casino",
      "region": "EU"
    }
  },
  "trigger": "scheduled",
  "value": {
    "current": {
      "score": 1234.45,
      "sequence": 4,
      "segment": "4. VIP",
      "date": "2023-11-20T13:45:00+02:00"
    },
    "previous": {
      "score": 1230.45,
      "sequence": 4,
      "segment": "4. VIP",
      "date": "2023-11-19T13:45:00+02:00"
    }
  },
  "sessionChurnRisk": {
    "current": {
      "score": 0.2,
      "sequence": 2,
      "segment": "2. Medium",
      "date": "2023-11-20T13:45:00+02:00"
    },
    "previous": {
      "score": 0.19634,
      "sequence": 1,
      "segment": "1. Low",
      "date": "2023-11-12T13:45:00+02:00"
    }
  },
  "churnRisk": {
    "current": {
      "score": 0.89634,
      "sequence": 3,
      "segment": "3. High",
      "date": "2023-11-20T13:45:00+02:00"
    }
  },
  "incentiveUsage": {
    "current": {
      "score": 4,
      "sequence": 4,
      "segment": "3. Bonus abuser",
      "date": "2023-11-20T13:45:00+02:00"
    }
  },
  "incentiveGuidance": {
    "current": {
      "score": 2,
      "sequence": 2,
      "segment": "2. Continue Incentives",
      "date": "2023-11-20T13:45:00+02:00"
    },
    "previous": {
      "score": 1,
      "sequence": 1,
      "segment": "1. Increase Incentives",
      "date": "2023-11-19T13:45:00+02:00"
    }
  },
  "reactivationPotential": {
    "current": {
      "score": 0.78,
      "sequence": 3,
      "segment": "3. High Potential",
      "date": "2023-11-20T13:45:00+02:00"
    }
  },
  "incentiveRecommendations": [
    {
      "recommendationId": "d164def1-c3c2-401e-8a09-1928f8765b0d",
      "rank": 1,
      "score": 87.17,
      "incentiveId": "1",
      "incentiveName": "Freebet",
      "amount": 2000
    },
    {
      "recommendationId": "24f4d856-b42d-4f38-ac62-cdbc6a0e85a8",
      "rank": 2,
      "score": 72.9,
      "incentiveId": "1",
      "incentiveName": "Freebet",
      "amount": 200
    }
  ],
  "favoriteGameCategories": [
    {
      "rank": 1,
      "score": 0.9876,
      "categoryId": "C-1",
      "categoryName": "Casino"
    }
  ],
  "recommendedGames": [
    {
      "rank": 1,
      "score": 0.7654,
      "gameId": "G-123",
      "gameName": "Golden Whale Super Spinner",
      "categoryId": "C-1",
      "categoryName": "Casino"
    }
  ]
}