# Events & screen tracking

> Track custom events, screen views and scene changes in your Unity game with the Grovs SDK.

Source: https://docs.grovs.io/docs/sdk/unity/analytics

Track custom events and screens, and identify the player. Installs, opens, time spent and reactivations are tracked by the native SDK with no code.

## Tracking custom events

`Track` records an event with optional properties and tags:

```csharp
using System.Collections.Generic;
using GrovsSDK;

Grovs.Track("level_complete",
    new Dictionary<string, object> { { "level", 3 }, { "stars", 2 } },
    new List<string> { "progress" });

Grovs.Track("tutorial_skipped");
```

Property values must be JSON-serializable: strings, numbers, booleans, `null`, lists and string-keyed dictionaries of these. Anything else throws `ArgumentException`. A `null` name throws `ArgumentNullException`.

### Event rules

Grovs logs a `[Grovs]` warning, and still sends the call, when an event breaks a native rule:

- The name is empty or reserved: `view`, `open`, `install`, `reinstall`, `app_open`, `time_spent`, `reactivation`, `user_referred`, `custom`, `screen_view`, `push_open`, `push_delivered`, `push_held`, `in_app_viewed`, `in_app_clicked`, `in_app_dismissed`, `in_app_answered`, `in_app_commented`, `in_app_held`, `journey_entered`, `journey_held`, `journey_path`.
- Properties are over 8192 bytes of JSON.
- More than 20 tags, or a tag over 255 characters.

What the native SDK then does with the event: [iOS event name rules](https://docs.grovs.io/docs/sdk/ios/analytics#event-name-rules).

### Global tags

Tags added to every event:

```csharp
Grovs.SetGlobalTags(new List<string> { "beta" });
Grovs.SetGlobalTags(null); // clears them
```

## Tracking screen views

```csharp
Grovs.TrackScreenView("Shop");
Grovs.TrackScreenView("Shop", new Dictionary<string, object> { { "tab", "coins" } });
```

Native automatic screen tracking is off in Unity games, so screens come only from `TrackScreenView` and [scene tracking](#tracking-scenes). Screen views can trigger [in-app messages](https://docs.grovs.io/docs/sdk/unity/in-app-messages) and are matched by excluded screens.

## Tracking scenes

Turn on **Track scenes** in **Project Settings → Grovs**. Each active scene change is then sent as a screen view with the scene name, once per change. The first scene is reported at startup.

## Screen name aliases

Rename screens for the dashboard:

```csharp
Grovs.SetScreenAliases(new Dictionary<string, string> { { "MainMenu", "Home" } });
```

Aliases apply to `TrackScreenView` and to scene tracking.

## Identifying the player

```csharp
Grovs.SetUserIdentifier("player-42");   // null clears it
Grovs.SetUserAttributes(new Dictionary<string, object> { { "plan", "pro" }, { "level", 12 } });
```

Attribute values follow the same JSON rules as event properties.

## Next steps

- [Revenue](https://docs.grovs.io/docs/sdk/unity/revenue): log purchases
- [In-app messages](https://docs.grovs.io/docs/sdk/unity/in-app-messages): campaigns triggered by these events and screens
- [Privacy & Consent](https://docs.grovs.io/docs/sdk/unity/privacy): what's held while Grovs is disabled