Loyalty Events Schema

Optimove's Loyalty & Gamification module emits a set of events as players progress through missions, earn rewards, gain experience, and level up. This reference documents each event and its attributes.

All events share a common set of base attributes:

Attribute	Type	Description
`ls_createdat`	number	Unix timestamp of when the event was created.
`ls_brandid`	string	Identifier of the brand the event belongs to.
`ls_playerid`	string	Identifier of the player the event relates to.

📘
Mission progress vs. completion
If a mission is completed, only ls_mission_completed is emitted — no ls_mission_progress events are emitted for that completion.

ls_mission_progress

Emitted as a player makes progress toward a mission objective.

Attribute	Type	Description
`ls_createdat`	number	Unix timestamp of when the event was created.
`ls_brandid`	string	Identifier of the brand.
`ls_playerid`	string	Identifier of the player.
`ls_objectiveid`	string	Identifier of the mission objective.
`ls_objectivename`	string	Display name of the mission objective.
`ls_progress`	number	Current progress value toward the goal.
`ls_goal`	number	Target value required to complete the objective.

ls_mission_completed

Emitted when a player completes a mission objective.

Attribute	Type	Description
`ls_createdat`	number	Unix timestamp of when the event was created.
`ls_brandid`	string	Identifier of the brand.
`ls_playerid`	string	Identifier of the player.
`ls_objectiveid`	string	Identifier of the mission objective.
`ls_objectivename`	string	Display name of the mission objective.
`ls_status`	string	Completion status of the mission.
`ls_rewardsjson`	string (optional)	JSON-encoded details of any rewards granted on completion.

ls_reward_claimed_from_mission

Emitted when a player claims a reward earned from a mission.

Attribute	Type	Description
`ls_createdat`	number	Unix timestamp of when the event was created.
`ls_brandid`	string	Identifier of the brand.
`ls_playerid`	string	Identifier of the player.
`ls_objectiveid`	string	Identifier of the mission objective the reward came from.
`ls_rewardsjson`	string	JSON-encoded details of the claimed reward(s).

ls_reward_claimed_from_leaderboard

Emitted when a player claims a reward earned from a leaderboard.

Attribute	Type	Description
`ls_createdat`	number	Unix timestamp of when the event was created.
`ls_brandid`	string	Identifier of the brand.
`ls_leaderboardid`	string	Identifier of the leaderboard the reward came from.
`ls_rewardsjson`	string	JSON-encoded details of the claimed reward(s).

ls_badge_earned

Emitted when a player earns a badge.

Attribute	Type	Description
`ls_createdat`	number	Unix timestamp of when the event was created.
`ls_brandid`	string	Identifier of the brand.
`ls_playerid`	string	Identifier of the player.
`ls_ruleid`	string (optional)	Identifier of the rule that triggered the badge, if applicable.
`ls_objectiveid`	string (optional)	Identifier of the associated objective, if applicable.
`ls_badgeid`	string	Identifier of the earned badge.
`ls_badgename`	string	Display name of the earned badge.

ls_virtual_currency_added

Emitted when virtual currency is added to a player's balance.

Attribute	Type	Description
`ls_createdat`	number	Unix timestamp of when the event was created.
`ls_brandid`	string	Identifier of the brand.
`ls_playerid`	string	Identifier of the player.
`ls_ruleid`	string (optional)	Identifier of the rule that triggered the award, if applicable.
`ls_objectiveid`	string (optional)	Identifier of the associated objective, if applicable.
`ls_currencyid`	string	Identifier of the virtual currency.
`ls_currencyname`	string	Display name of the virtual currency.
`ls_amount`	number	Amount of currency added.

ls_experience_points_gained

Emitted when a player gains experience points.

Attribute	Type	Description
`ls_createdat`	number	Unix timestamp of when the event was created.
`ls_brandid`	string	Identifier of the brand.
`ls_playerid`	string	Identifier of the player.
`ls_ruleid`	string (optional)	Identifier of the rule that triggered the award, if applicable.
`ls_objectiveid`	string (optional)	Identifier of the associated objective, if applicable.
`ls_leaderboardid`	string (optional)	Identifier of the associated leaderboard, if applicable.
`ls_rewardid`	string	Identifier of the experience-point reward.
`ls_rewardname`	string	Display name of the reward.
`ls_amount`	number	Amount of experience points gained.

ls_external_reward_claimed

Emitted when a player claims an external reward from a mission, leaderboard, or level.

Attribute	Type	Description
`ls_createdat`	number	Unix timestamp of when the event was created.
`ls_brandid`	string	Identifier of the brand.
`ls_playerid`	string	Identifier of the player.
`ls_ruleid`	string (optional)	Identifier of the rule that triggered the reward, if applicable.
`ls_objectiveid`	string (optional)	Identifier of the associated objective, if applicable.
`ls_leaderboardid`	string (optional)	Identifier of the associated leaderboard, if applicable.
`ls_rewardid`	string	Identifier of the claimed reward.
`ls_rewardname`	string	Display name of the claimed reward.
`ls_shortcode`	string (optional)	Short code associated with the reward, if applicable.
`ls_source`	string	Source of the reward. One of `mission`, `leaderboard`, `level`, or `store`.

ls_player_level_up

Emitted when a player advances to a new level.

Attribute	Type	Description
`ls_createdat`	number	Unix timestamp of when the event was created.
`ls_brandid`	string	Identifier of the brand.
`ls_playerid`	string	Identifier of the player.
`ls_levelconfigid`	string	Identifier of the level configuration.
`ls_levelid`	string	Identifier of the level reached.
`ls_levelnumber`	number	Numeric position of the level reached.
`ls_levelname`	string	Display name of the level reached.

ls_mission_unlocked

Emitted when a previously locked mission becomes available to the player — by reaching a gating level, completing a prerequisite mission, earning a gating badge, or unlocking the mission by spending currency. ls_unlockedby identifies which condition made the mission available.

Attribute	Type	Description
`ls_createdat`	number	Unix timestamp of when the event was created.
`ls_brandid`	string	Identifier of the brand.
`ls_playerid`	string	Identifier of the player.
`ls_objectiveid`	string	Identifier of the mission objective that was unlocked.
`ls_objectivename`	string	Display name of the mission objective that was unlocked.
`ls_unlockedby`	string	Condition that unlocked the mission. One of `level`, `mission`, `badge`, or `purchase`.

ls_store_item_purchased

Emitted once when a player buys a single store item.

📘
One event per fresh purchase
This event is emitted only on a fresh purchase. Idempotent retries of the same buy do not emit a second event.

Attribute	Type	Description
`ls_createdat`	number	Unix timestamp of when the event was created.
`ls_brandid`	string	Identifier of the brand.
`ls_playerid`	string	Identifier of the player.
`ls_purchaseid`	string	Identifier of the purchase. Use this to de-duplicate downstream.
`ls_storeitemid`	string	Identifier of the purchased store item.
`ls_storeitemtitle`	string	Display title of the purchased store item.
`ls_pricecurrencyid`	string	Identifier of the virtual currency the item was priced in.
`ls_baseprice`	number	List price of the item before any discount, in `ls_pricecurrencyid`.
`ls_effectiveprice`	number	Price actually charged to the player after any discount.
`ls_discountgroupid`	string (optional)	Identifier of the discount group applied to the purchase, if any.
`ls_rewardid`	string	Identifier of the reward granted by the item.
`ls_rewardquantity`	number	Quantity of the reward granted.

ls_store_bundle_purchased

Emitted once when a player buys a bundle. A single event is emitted per bundle purchase, carrying every member item in ls_itemsjson.

📘
One event per fresh purchase
This event is emitted only on a fresh purchase. Idempotent retries of the same buy do not emit a second event.

Attribute	Type	Description
`ls_createdat`	number	Unix timestamp of when the event was created.
`ls_brandid`	string	Identifier of the brand.
`ls_playerid`	string	Identifier of the player.
`ls_purchaseid`	string	Identifier of the purchase. Use this to de-duplicate downstream.
`ls_bundleid`	string	Identifier of the purchased bundle.
`ls_bundletitle`	string	Display title of the purchased bundle.
`ls_pricecurrencyid`	string	Identifier of the virtual currency the bundle was priced in.
`ls_baseprice`	number	List price of the bundle before any discount, in `ls_pricecurrencyid`.
`ls_effectiveprice`	number	Price actually charged to the player after any discount.
`ls_discountgroupid`	string (optional)	Identifier of the discount group applied to the purchase, if any.
`ls_itemsjson`	string	JSON-encoded array of the bundle's member items. See the structure below.

ls_itemsjson is a JSON-encoded array with one entry per bundle member:

[
  {
    "storeItemId": "item_123",
    "title": "50 Gems",
    "rewardId": "reward_456",
    "rewardQuantity": 50
  }
]