> For the complete documentation index, see [llms.txt](https://docs.candy-smith.com/main/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.candy-smith.com/main/general-info/analytics/unity-analytics.md).

# unity analytics

Unity Analytics is the default analytics provider.

The Unity Analytics package is referenced through the Unity Package Manager. Custom event schemas and funnels must exist in the selected Unity Gaming Services environment before the game can send custom events.

## Unity Analytics Schema Setup Wizard

Open:

```
HomeDesignMatch3Kit > Settings > Analytics Schema Setup
```

<figure><img src="https://2423037410-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FixseEfHbM88cpcinnJo4%2Fuploads%2FqGfWa2WkX9zJHR99VeN5%2Fimage.png?alt=media&amp;token=eb816003-ccc7-432d-af35-2ca07ed209ad" alt=""><figcaption></figcaption></figure>

The wizard contains four steps:

{% stepper %}
{% step %}

## Connect the Unity project

1. Select `Authorize Unity Editor` and sign in with the buyer's Unity ID.
2. Select `Link Project` and link the buyer's Unity Gaming Services project.
3. Select `Select Environment` and choose the environment used by the game.
4. Select `Refresh Status`.

The `Review Events` button becomes available only when the Unity ID, organization, project, project ID, and environment are available.

Use a test environment during development and a production environment for the release build.
{% endstep %}

{% step %}

## Review the analytics schema

The wizard displays all events and funnels included in the kit.

Review the schema before publishing it to the selected environment.

The wizard also displays a special note about Unity's standard `adImpression` event.
{% endstep %}

{% step %}

## Populate Unity Analytics

Select:

```
Populate Events
```

The wizard uses the authenticated Unity Editor session to create or update:

* analytics parameters;
* custom event schemas;
* event descriptions;
* missing event parameters;
* analytics funnels.

The operation is safe to run again. Existing definitions are reused, incomplete events are updated, and duplicates are not intentionally created.

The Unity ID must have permissions to manage events and funnels in the buyer's UGS project.

A `403 Forbidden` response usually means that:

* Analytics is not enabled for the project;
* the Unity ID does not have permission to manage events;
* the Unity ID does not have permission to manage funnels.
  {% endstep %}

{% step %}

## Verify the setup

After publishing, select:

```
Open Unity Analytics Event Manager
```

Verify the created event schemas and funnels in the Unity Dashboard.
{% endstep %}
{% endstepper %}

## Unity Analytics IDs

No Unity Analytics IDs are hard-coded in the asset.

There are no Unity Analytics ID fields in `GameSettings`.

The wizard reads all required IDs from the Unity Editor and the active UGS environment.

| Value           | Source                                                                             | Enter manually? |
| --------------- | ---------------------------------------------------------------------------------- | --------------- |
| Organization ID | Organization of the linked Unity Cloud project                                     | No              |
| Project ID      | UGS project linked in `Edit > Project Settings > Services`                         | No              |
| Environment ID  | Active environment selected in `Edit > Project Settings > Services > Environments` | No              |

If the project or environment is changed, select `Refresh Status` before continuing.

The schemas are created only in the currently selected environment. They are not automatically created in every environment.

## Are Unity Analytics events added manually?

No.

For the events listed below, the `Populate Events` button performs the Event Manager setup automatically.

It creates missing parameters, creates missing custom events, enables incomplete events, updates descriptions, adds missing parameters, and creates missing funnels.

Unity's standard `adImpression` event is handled separately. The wizard does not create a custom event named `ad_impression`.

At runtime, the kit maps `ad_impression` to Unity Analytics' standard ad impression event.

If the wizard cannot be used, select:

```
Copy Schema Checklist
```

Then create the custom events and parameters manually in Unity Analytics Event Manager.

Funnels must be created manually if the wizard is not used.

## Custom event schemas

Parameter names and types are case-sensitive.

| Event               | Parameters                                                                                                         |
| ------------------- | ------------------------------------------------------------------------------------------------------------------ |
| `gameplay_entered`  | `level_number` — INTEGER                                                                                           |
| `level_started`     | `level_number` — INTEGER; `attempt_number` — INTEGER                                                               |
| `level_completed`   | `level_number` — INTEGER; `attempt_number` — INTEGER; `duration_sec` — FLOAT; `score` — INTEGER; `stars` — INTEGER |
| `level_failed`      | `level_number` — INTEGER; `attempt_number` — INTEGER; `duration_sec` — FLOAT; `fail_reason` — STRING               |
| `popup_opened`      | `popup_id` — STRING; `level_number` — INTEGER                                                                      |
| `popup_closed`      | `popup_id` — STRING; `popup_result` — STRING; `duration_sec` — FLOAT; `level_number` — INTEGER                     |
| `ad_completed`      | `ad_provider` — STRING; `placement_id` — STRING; `ad_type` — STRING                                                |
| `ad_reward_granted` | `ad_provider` — STRING; `placement_id` — STRING; `ad_type` — STRING                                                |
| `ad_show_failed`    | `ad_provider` — STRING; `placement_id` — STRING; `ad_type` — STRING                                                |
| `ad_clicked`        | `ad_provider` — STRING; `placement_id` — STRING; `ad_type` — STRING                                                |
| `iap_started`       | `product_id` — STRING                                                                                              |
| `iap_completed`     | `product_id` — STRING                                                                                              |
| `iap_failed`        | `product_id` — STRING; `fail_reason` — STRING                                                                      |

## Automatically tracked events

* `AnalyticsEventTracker` tracks gameplay entry.
* `AnalyticsEventTracker` tracks level start, completion, and failure.
* `AnalyticsEventTracker` tracks popup open and close events.
* `AnalyticsEventTracker` tracks IAP start, completion, and failure.
* `AdsListener` tracks ad impressions.
* `AdsListener` tracks ad completion, reward, failure, and click events.

Game code does not need to call a different API for each analytics provider.

All events are sent through the selected `IAnalyticsService` implementation.

## Unity Analytics funnels

The wizard creates the following funnels:

| Funnel                                    | Steps                                                   |
| ----------------------------------------- | ------------------------------------------------------- |
| `HomeDesignMatch3Kit - Level Progression` | `level_completed` with `level_number` 1 → 2 → 3 → 4 → 5 |
| `HomeDesignMatch3Kit - First Purchase`    | `iap_started` → `iap_completed`                         |
| `HomeDesignMatch3Kit - Rewarded Ad`       | `ad_completed` → `ad_reward_granted`                    |

Funnels are created in the selected environment and use a 30-day duration filter.

## Official documentation

* [Configure a project for Unity Cloud](https://docs.unity.com/en-us/cloud/projects/configure-project-for-unity-cloud)
* [Create a custom Unity Analytics event](https://docs.unity.com/en-us/analytics/events/custom-event)
* [Copy custom events to another environment](https://docs.unity.com/en-us/analytics/events/copy-custom-events-to-another-environment)