Records (Events)

Records

Records (also known as Game Events) are logs of meaningful in-game or out-of-game actions that can be tracked through the SDK or REST server. They serve as the primary mechanism for recording gameplay activity, progression, and user interactions.

---

Match vs. Non-Match Contexts

Records are categorized into two contexts:

In-Match Records

post /api/BlockchainStorage/records/match/add

These records are tied to an active match session (identified by a non-zero matchSessionId) and represent events that occur during level or match gameplay.

Examples:

• Player kills (against other players, NPCs, or AI)

• Deaths (if they don’t end the match for the player)

• Item pickups (e.g., bounty items, power-ups)

• Item usage

• Special attacks

---

Out-of-Match Records

post /api/BlockchainStorage/records/menu/add

These are logged with matchSessionId: 0 and represent actions that occur outside of active gameplay, such as in menus or metagame screens.

Examples:

• Level or item unlocks

• Purchases (upgrades, consumables, etc.)

• Redeeming codes or entering special coupons

---

Submitting Records

Records can be submitted individually or in batches.

Batch records outside of match (level), eg Menu

post /api/BlockchainStorage/records/menu/batch

Batch records inside of match (level)

post /api/BlockchainStorage/records/match/batch

When submitting in batch mode, it is recommended to keep the number of records per request under 20 for performance and reliability.

🔧 JSON Format

Null optional values can be left as null (not included in the call) and the default values will be picked up. PlayerIndex will equal to the user account making the call. Otherplayers will remain empty. StartTime will be set to the time of the call (now).

{
  "matchSessionId": 0,
  "score": 0,
  "key": "string",
  "value": "string",
  "playerIndex": null,
  "otherPlayers": null,
  "startTime": null
}

Field	Description
matchSessionId	The match session this record is tied to. Use 0 for out-of-match records.
score	Optional score value. Set to 0 if not used.
key	Event key name. Describes the type of event.
value	Event value. Specific context or detail of the key.
playerIndex	Optional player index. Used when identifying a specific player.
otherPlayers	Optional array of player indices involved in the event.
startTime	Optional timestamp for the event start.

---

Example Key-Value Pairs

Key	Value	Use Case
pickup	mushroom	Item collected
pickup	leaf	Item collected
kill	goomba	Enemy defeated
kill	koopa	Enemy defeated
level-unlock	green island	Level unlocked
level-unlock	red mountain	Level unlocked

---

Best Practices

• Use clear and consistent key names to simplify filtering and analysis.

• Avoid excessive batching; aim for ≤ 20 records per request.

• Log all impactful gameplay and progression events for better analytics and rewards logic.

---

Need help integrating record logging? See the SDK Integration Guide or contact support.