Foundation event

This content is for the 2.10.0 version. Switch to the latest version for up-to-date documentation.

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

Field	Type	Description
`player`required	object
`trigger`optional	`scheduledsession`	What produced this event: 'scheduled' (batch run) or 'session' (real-time). All predictions in one event share this trigger.
`customerLTV`optional	lifeTimeValuePrediction
`churnRisk`optional	churnRiskPrediction
`sessionChurnRisk`optional	sessionChurnRiskPrediction
`incentiveUsage`optional	incentiveUsagePrediction
`incentiveGuidance`optional	incentiveGuidancePrediction
`reactivationPotential`optional	reactivationPotentialPrediction
`incentiveRecommendations`optional	array of incentiveRecommendation
`favoriteGameCategories`optional	array of favoriteGameCategory
`recommendedGames`optional	array of recommendedGame

Player

Field	Type	Description
`id`required	string
`cohort`required	number
`group`required	`TargetControl`
`siteId`optionaldeprecated	number	DEPRECATED: use `metadata` instead (e.g. metadata.siteId). Retained for backward compatibility and will be removed in a future major version.
`metadata`optional	object	Free-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.

lifeTimeValuePrediction

Field	Type	Description
`current`required	lifeTimeValuePredictionEntry
`previous`optional	lifeTimeValuePredictionEntry

lifeTimeValuePredictionEntry

Field	Type	Description
`score`required	number	Life-Time Value Score
`sequence`required	numbermin 1 / max 4	A numeric representation of the player based on the LTV score
`segment`required	`1. Low2. Core3. High4. VIP`	The segment name of the player based on the LTV score
`date`required	string	ISO8601 date-time

churnRiskPrediction

Field	Type	Description
`current`required	churnRiskPredictionEntry
`previous`optional	churnRiskPredictionEntry

churnRiskPredictionEntry

Field	Type	Description
`score`required	numbermin 0 / max 1	Churn Risk Score
`sequence`required	numbermin 1 / max 4	A numeric representation of the player based on the churn risk score
`segment`required	`1. Low2. Medium3. High4. Dormant`	The segment name of the player based on the Risk Score
`date`required	string	ISO8601 date-time

sessionChurnRiskPrediction

Field	Type	Description
`current`required	sessionChurnRiskPredictionEntry
`previous`optional	sessionChurnRiskPredictionEntry

sessionChurnRiskPredictionEntry

Field	Type	Description
`score`required	numbermin 0 / max 1	Session Churn Risk Score
`sequence`required	numbermin 1 / max 4	A numeric representation of the player based on the churn risk score
`segment`required	`1. Low2. Medium3. High4. Dormant`	The segment name of the player based on the Risk Score
`date`required	string	ISO8601 date-time

incentiveUsagePrediction

Field	Type	Description
`current`required	incentiveUsagePredictionEntry
`previous`optional	incentiveUsagePredictionEntry

incentiveUsagePredictionEntry

Field	Type	Description
`score`required	number	Incentive Usage Score
`sequence`required	numbermin 1 / max 4	A numeric representation of the player based on the churn risk score
`segment`required	`0. No bonus usage1. Normal bonus usage2. Increased bonus usage3. Bonus abuser`	The segment name of the player based on the incentive usage score
`date`required	string	ISO8601 date-time

incentiveGuidancePrediction

Field	Type	Description
`current`required	incentiveGuidancePredictionEntry
`previous`optional	incentiveGuidancePredictionEntry

incentiveGuidancePredictionEntry

Field	Type	Description
`score`required	number	Incentive Guidance Score
`sequence`required	numbermin 1 / max 4	A numeric representation of the recommended incentive posture
`segment`required	`1. Increase Incentives2. Continue Incentives3. Limit Incentives4. Avoid Incentives`	Recommended incentive posture for the player
`date`required	string	ISO8601 date-time

reactivationPotentialPrediction

Field	Type	Description
`current`required	reactivationPotentialPredictionEntry
`previous`optional	reactivationPotentialPredictionEntry

reactivationPotentialPredictionEntry

Field	Type	Description
`score`required	numbermin 0 / max 1	Reactivation Potential Score
`sequence`required	numbermin 1 / max 3	A numeric representation of the player's reactivation potential
`segment`required	`1. Low Potential2. Medium Potential3. High Potential`	The segment name of the player's reactivation potential
`date`required	string	ISO8601 date-time

incentiveRecommendation

Field	Type	Description
`recommendationId`required	string	Unique identifier for this recommendation emission
`rank`required	number	1-based rank of the recommendation for the player
`score`required	number	Score
`incentiveId`required	string	Identifier of the recommended incentive type
`incentiveName`required	string	Incentive Name
`amount`required	number	Amount
`triggerId`optional	string	Identifier of the trigger this recommendation came from

favoriteGameCategory

Field	Type	Description
`rank`required	number
`score`required	number
`categoryId`required	string
`categoryName`required	string

recommendedGame

Field	Type	Description
`rank`required	number
`score`required	number
`gameId`required	string
`gameName`required	string
`categoryId`required	string
`categoryName`required	string

Example payload

The same event as JSON and as a single flattened CSV row. model_dump_csv() (available from 2.11.0) produces the CSV form: nested objects become _-joined snake_case columns, list fields are JSON-encoded into one column, and unset fields are omitted — so the column set varies per event.

JSON
CSV

{
  "player": {
    "id": "PLAYER-ID-AS-GUID-OR-NUMERIC-123",
    "cohort": 1,
    "group": "Target",
    "metadata": {
      "siteId": 123,
      "brand": "GoldenWhale",
      "region": "EU"
    }
  },
  "trigger": "scheduled",
  "customerLTV": {
    "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,
      "triggerId": "weekly-freebet-42"
    },
    {
      "recommendationId": "24f4d856-b42d-4f38-ac62-cdbc6a0e85a8",
      "rank": 2,
      "score": 72.9,
      "incentiveId": "1",
      "incentiveName": "Freebet",
      "amount": 200,
      "triggerId": "winback-offer-7"
    }
  ],
  "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"
    }
  ]
}

player_id,player_cohort,player_group,player_metadata_siteId,player_metadata_brand,player_metadata_region,trigger,customer_ltv_current_score,customer_ltv_current_sequence,customer_ltv_current_segment,customer_ltv_current_date,customer_ltv_previous_score,customer_ltv_previous_sequence,customer_ltv_previous_segment,customer_ltv_previous_date,session_churn_risk_current_score,session_churn_risk_current_sequence,session_churn_risk_current_segment,session_churn_risk_current_date,session_churn_risk_previous_score,session_churn_risk_previous_sequence,session_churn_risk_previous_segment,session_churn_risk_previous_date,churn_risk_current_score,churn_risk_current_sequence,churn_risk_current_segment,churn_risk_current_date,incentive_usage_current_score,incentive_usage_current_sequence,incentive_usage_current_segment,incentive_usage_current_date,incentive_guidance_current_score,incentive_guidance_current_sequence,incentive_guidance_current_segment,incentive_guidance_current_date,incentive_guidance_previous_score,incentive_guidance_previous_sequence,incentive_guidance_previous_segment,incentive_guidance_previous_date,reactivation_potential_current_score,reactivation_potential_current_sequence,reactivation_potential_current_segment,reactivation_potential_current_date,incentive_recommendations,favorite_game_categories,recommended_games
PLAYER-ID-AS-GUID-OR-NUMERIC-123,1,Target,123,GoldenWhale,EU,scheduled,1234.45,4,4. VIP,2023-11-20T13:45:00+02:00,1230.45,4,4. VIP,2023-11-19T13:45:00+02:00,0.2,2,2. Medium,2023-11-20T13:45:00+02:00,0.19634,1,1. Low,2023-11-12T13:45:00+02:00,0.89634,3,3. High,2023-11-20T13:45:00+02:00,4,4,3. Bonus abuser,2023-11-20T13:45:00+02:00,2,2,2. Continue Incentives,2023-11-20T13:45:00+02:00,1,1,1. Increase Incentives,2023-11-19T13:45:00+02:00,0.78,3,3. High Potential,2023-11-20T13:45:00+02:00,"[{""recommendation_id"": ""d164def1-c3c2-401e-8a09-1928f8765b0d"", ""rank"": 1, ""score"": 87.17, ""incentive_id"": ""1"", ""incentive_name"": ""Freebet"", ""amount"": 2000, ""trigger_id"": ""weekly-freebet-42""}, {""recommendation_id"": ""24f4d856-b42d-4f38-ac62-cdbc6a0e85a8"", ""rank"": 2, ""score"": 72.9, ""incentive_id"": ""1"", ""incentive_name"": ""Freebet"", ""amount"": 200, ""trigger_id"": ""winback-offer-7""}]","[{""rank"": 1, ""score"": 0.9876, ""category_id"": ""C-1"", ""category_name"": ""Casino""}]","[{""rank"": 1, ""score"": 0.7654, ""game_id"": ""G-123"", ""game_name"": ""Golden Whale Super Spinner"", ""category_id"": ""C-1"", ""category_name"": ""Casino""}]"