Player Analytics

# Player Analytics

Player Analytics adds Network Storage activity and game-reported events to the sboxcool.com player timeline. It helps you answer who played recently, what happened during a session, which endpoints or storage actions ran, where tracked values changed, and where players hit warnings or errors.

Analytics settings are managed from your project dashboard under **Settings → Analytics**. The s&box library reads the same runtime configuration used by Network Storage security features, so event reporting can be enabled, disabled, or narrowed without rebuilding your game.

## What Player Analytics captures

Projects with no explicit analytics settings are treated as enabled. Depending on your settings, Network Storage can record:

- Session joins, leaves, heartbeats, and managed-library status
- Endpoint calls
- Storage loads and saves
- Tracked currency, XP, and stat deltas
- Warning and error reports from your game
- Allowlisted custom game events
- Lightweight performance samples reported by the managed analytics runtime

Open **Game Analytics** from a project to see recent players, session status, total playtime, player timelines, and health signals.

## Dashboard settings

Go to **Network Storage → Your Project → Settings → Analytics** to configure what is stored.

| Setting | What it controls |
|---|---|
| Analytics enabled | Master switch for Player Analytics collection. |
| Capture sessions | Session joins, leaves, heartbeats, playtime, and online/offline state. |
| Capture endpoints | Endpoint execution timeline entries. |
| Capture storage | Direct storage load/save timeline entries. |
| Capture tracked fields | Explicit currency, XP, and stat deltas. |
| Capture warnings | Recoverable warning reports from the game. |
| Capture errors | Non-fatal error reports from the game. |
| Managed library events | Custom events and managed runtime reports from the official library. |
| Retain error stacks | Whether error stack traces may be stored. Off by default. |
| Retain warning context | Whether warning context payloads may be retained. |
| Allowed event types | Custom event names your game is allowed to send. |
| Quiet endpoint slugs | Endpoint slugs hidden from noisy dashboard summaries. |

## Tracked fields

Tracked fields are explicit. The dashboard can suggest numeric fields from collection schemas and high-confidence `_ledger: true` fields, but a field is only treated as currency, XP, or a stat after it is saved in analytics settings.

Examples:

- `profile.gold` as currency
- `profile.fishing_xp` as XP
- `profile.fishCaught` as stat

Use tracked fields for values that matter to progression, economy, balance, or abuse investigation. Prefer tracking the authoritative value stored by an endpoint rather than a client-only display value.

## Primary player table

The analytics settings can point at a primary player collection/table so the dashboard can show player-friendly context instead of only a Steam ID.

Typical setup:

- Collection: your profile/player collection
- User ID field: `$key` for per-SteamID collections, or the field containing the Steam ID for table-like data
- Display name field: a safe public name field, if you store one
- Summary columns: a small set of fields such as level, gold, rank, or region

Do not choose private fields as display or summary columns.

## Custom events

Custom event types must be allowlisted in project analytics settings before the library sends them. Event names are normalized to lowercase identifiers such as `cast_line`, `caught_fish`, or `sold_fish`.

```csharp
await NetworkStorageAnalytics.TrackEvent( "cast_line", new
{
    rod = "starter",
    zone = "reef"
} );

await NetworkStorageAnalytics.TrackEvent( "caught_fish", new
{
    fish = "salmon",
    weight = 4.2f,
    rarity = "rare"
} );
```

Use custom events for gameplay milestones or investigation breadcrumbs, not for high-frequency telemetry every frame.

## Warnings

Warnings are for recoverable pain points and UX friction. They appear alongside the player's timeline when warning capture is enabled.

```csharp
await NetworkStorageAnalytics.Warning( "inventory_ui_failed", "Inventory panel failed to open", new
{
    screen = "shop",
    item = "bait_pack"
} );
```

Good warning examples:

- A UI panel failed to open
- An optional reward animation could not play
- A player action had to be retried
- A fallback path was used after a recoverable failure

## Errors

Errors are for non-fatal gameplay reporting. Analytics failures are swallowed by the library and only written to local Network Storage logs when logging is enabled, so reporting an error should not break gameplay.

```csharp
try
{
    await SellFish();
}
catch ( Exception ex )
{
    await NetworkStorageAnalytics.Error( ex, "sell_fish_failed", new
    {
        fishCount = 12
    } );
}
```

Stack traces are sent only when the project analytics config allows stack retention. Leave stack retention off unless you need it for debugging and are comfortable with the privacy implications.

## Managed sessions

The official library creates a lightweight managed analytics runtime after Network Storage is configured. When managed analytics and session capture are enabled, it can report session start, leave, periodic heartbeats, and FPS summary samples.

You can also report manual session boundaries:

```csharp
await NetworkStorageAnalytics.SessionStart();
await NetworkStorageAnalytics.SessionEnd( durationSeconds: 600 );
```

Manual session calls are useful when your game has its own round, match, or activity lifecycle. If you use both automatic and manual session reporting, include context that makes the session type clear.

## Manual HTTP ingestion

Most games should use the s&box library. Trusted tooling or custom clients can report events directly with the public API key:

```http
POST /v3/storage/{projectId}/analytics/events
X-API-Key: sbox_ns_...
Content-Type: application/json
```

```json
{
  "steamId": "76561198000000000",
  "severity": "custom",
  "type": "caught_fish",
  "label": "Caught fish",
  "context": {
    "fish": "salmon",
    "rarity": "rare"
  }
}
```

Supported severities are `custom`, `warning`, `error`, `info`, and `session`. Custom events still require an allowlisted event type. If s&box auth is required for the project, analytics requests must include the same auth context as other runtime requests.

## Payload safety and limits

Do not send API keys, auth tokens, passwords, payment information, or player private information in analytics payloads. The server bounds request and stored payload sizes and redacts obvious secret fields where practical, but game code should still avoid sending secrets.

Current safety behavior:

- Event request bodies are limited to 32 KB.
- Stored event payloads are compacted to a smaller bounded payload.
- Obvious secret fields such as tokens, passwords, authorization headers, and API keys are redacted.
- Long messages and stack traces are truncated.
- Stack traces are dropped unless error stack retention is enabled.

## Troubleshooting

| Symptom | Check |
|---|---|
| Custom event is not appearing | Confirm Analytics is enabled, Managed library events are enabled, and the event type is in the allowlist. |
| Warnings or errors are missing | Confirm Capture warnings or Capture errors is enabled. |
| Stack trace is missing | Enable Retain error stacks in analytics settings. |
| Player shows as server-only | The player only has server-side endpoint/storage activity. Managed library events start marking players as managed. |
| Too many noisy endpoint entries | Add low-value endpoint slugs to Quiet endpoint slugs. |

## Related documentation

- [Library Setup Guide](/wiki/network-storage-v3/library-setup)
- [s&box Auth](/wiki/network-storage-v3/sbox-auth)
- [Endpoints](/wiki/network-storage-v3/endpoints)
- [Quotas & Usage](/wiki/network-storage-v3/quotas-and-usage)