> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rolearn.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# SDK Event Types

> The 13 built-in event types the Multiplatform SDK can send, and what each rolls up into

Every event shares a common envelope, then a per-type `payload`:

```json theme={null}
{
  "event_id":   "uuid-v4",
  "ts":         "2026-06-18T10:00:00Z",
  "platform":   "roblox | steam | unity | fortnite",
  "game_id":    "920587237",
  "player_id":  "hashed-player-id or null",
  "session_id": "uuid-v4",
  "type":       "session_start | purchase | ...",
  "payload":    {}
}
```

`event_id` is deduped within 24h, so retries on network failure are safe.

## The 13 built-in types

| Type               | Auto-emitted?             | Required payload                   | Rolls up into                          |
| ------------------ | ------------------------- | ---------------------------------- | -------------------------------------- |
| `session_start`    | Yes (join)                | —                                  | DAU/WAU/MAU, geo                       |
| `session_end`      | Yes (leave)               | —                                  | session length, playtime, retention    |
| `purchase`         | Manual / gamepass hook    | `sku`, `price`                     | ARPDAU, revenue timeline, top products |
| `performance`      | Yes (Roblox, per session) | `fps_avg`                          | FPS histogram, p5/p50/p95              |
| `crash`            | Yes (Roblox LogService)   | `stack_trace`                      | crash groups, top crashes              |
| `error`            | Yes (Roblox LogService)   | `severity`, `message`              | error feed                             |
| `ad_impression`    | Manual                    | `format`, `network`, `revenue_usd` | ARPDAU-ads, eCPM, ad revenue           |
| `brand_zone_enter` | Manual                    | `zone_id`                          | brand-zone reach                       |
| `brand_zone_exit`  | Manual                    | `zone_id`                          | brand-zone dwell time                  |
| `equip`            | Manual                    | item id                            | repeat-equip / brand-asset usage       |
| `share`            | Manual                    | —                                  | share counts                           |
| `level`            | Manual                    | `level`                            | stored + searchable (no rollup)        |
| `custom`           | Manual                    | `name`                             | stored + searchable (no rollup)        |

<Note>
  `level`, `custom`, and any unrecognized `type` are stored verbatim and are
  searchable in the Event Explorer, but are **not** aggregated into a dashboard.
</Note>

## Examples

<CodeGroup>
  ```json session_start theme={null}
  { "type": "session_start",
    "payload": { "country": "US", "membership": "Premium" } }
  ```

  ```json purchase theme={null}
  { "type": "purchase",
    "payload": { "sku": "vip_pass", "price": 4.99,
                 "currency": "ROBUX", "quantity": 1, "source": "gamepass" } }
  ```

  ```json ad_impression theme={null}
  { "type": "ad_impression",
    "payload": { "format": "rewarded", "network": "AdGuru",
                 "revenue_usd": 0.0012, "placement": "end_of_round", "ecpm": 1.20 } }
  ```

  ```json crash theme={null}
  { "type": "crash",
    "payload": { "stack_trace": "Workspace.Script:42: attempt to index nil...",
                 "build": "v1.4.2", "os": "Windows" } }
  ```
</CodeGroup>

For complete per-type field tables and validation rules, see the dedicated
**[SDK docs → Event types reference](https://rolearn.dev/sdk-docs)**.

## Validation rules

| Rule                                          | Behaviour                  |
| --------------------------------------------- | -------------------------- |
| `purchase` missing `sku` or `price`           | `422 Unprocessable Entity` |
| Payload with PII-shaped key/value (any depth) | `422` PII guard            |
| Duplicate `event_id` within 24h               | Silently deduped, `202`    |
| `(platform, game_id)` not linked to your team | `403`                      |
| Batch size > 500 events                       | `413`                      |
| Monthly quota exceeded                        | `429` with `Retry-After`   |