# 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).

```json
{
  "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.