Analytics
Overview
The Unity Analytics Collect API allows you to submit events related to your game for analysis.
Unity offers support for Analytics within the Unity Editor version 2019.4 and above. This is done through our SDK package (see the Useful Links section below). Using the SDK provides you with some benefits like automatic batching of events and automatic retries of event submissions which fail due to network issues. If you use the SDK to send events, you do not need to use this API.
In some cases you may not be able to use the SDK, for example:
- Sending events from a game server
- Sending events from a non-Unity game
In these cases you can use this API.
You can send either Standard Events or Custom Events, which are configured per environment. To see a list of Event types (Standard or Custom) or to define new Custom event types, you can use the Event Manager.
In the request body, specify a JSON document corresponding to the event type.
To verify whether the event has been processed by our service, check the Event Browser to see events coming in from your game.
For requests originating in China, to comply with China's Personal Information Protection Law (PIPL) you are required to set headers to indicate whether the user has consented to have their personal information processed. Requests made from China which do not have these headers set will result in no data being recorded by Unity Analytics.
Useful Links
Download OpenAPI specification:
Submit event(s)
You may submit either a single event or a list of events to this endpoint. When possible, sending a list of events is preferable due to efficiencies in connection pooling. Keep the POST length below 5MB; anything above might be rejected.
Header parameters for "{title}"
The presence of this header will indicate the player has granted consent to their data being sent out of China for processing. Players who do not consent should not have this header set on requests. The value of the header does not matter. This header is only required if the request originates in China.
Request body for "{title}"
Media Type:
application/jsonThe authenticated playerID, provided by the Unity authentication service. This can be useful to link analytics data to player accounts if you're using other Unity services (such as Cloud Save). If you're not using the Unity authentication service, this field should be omitted.
A unique string value that’s persisted for the duration of each player gameplay session and regenerated with each new gameplay session. The sessionID should be sent with every event the player triggers in their session.
There might be occasions when you want to send events containing valuable player information outside a player session and don’t have access to a sessionID. These are called GHOST events and you should omit the sessionID parameter and value on these events to ensure that they're not included in any player session calculations.
Adding eventUUID to an event will prevent the event being inserted twice within a 24 hour period. This may happen when e.g. a network time-out occurs, even if the event has already been processed by Unity Analytics. Should be unique per event.
If eventTimestamp is missing, the server will infer the timestamp based on the time the event was received. The date format should be as follows: where can be included to indicate offset from UTC.
yyyy-MM-dd HH:mm:ss.SSS ±[hh]:[mm]±[hh]:[mm]The authenticated playerID, provided by the Unity authentication service. This can be useful to link analytics data to player accounts if you're using other Unity services (such as Cloud Save). If you're not using the Unity authentication service, this field should be omitted.
A unique string value that’s persisted for the duration of each player gameplay session and regenerated with each new gameplay session. The sessionID should be sent with every event the player triggers in their session.
There might be occasions when you want to send events containing valuable player information outside a player session and don’t have access to a sessionID. These are called GHOST events and you should omit the sessionID parameter and value on these events to ensure that they're not included in any player session calculations.
Adding eventUUID to an event will prevent the event being inserted twice within a 24 hour period. This may happen when e.g. a network time-out occurs, even if the event has already been processed by Unity Analytics. Should be unique per event.
If eventTimestamp is missing, the server will infer the timestamp based on the time the event was received. The date format should be as follows: where can be included to indicate offset from UTC.
yyyy-MM-dd HH:mm:ss.SSS ±[hh]:[mm]±[hh]:[mm]Code samples for "{title}":
Request example
curl -X POST \ -H "PIPL_CONSENT: <PIPL_CONSENT>" \ -H "PIPL_EXPORT: <PIPL_EXPORT>" \ -H "Content-Type: application/json" \ -d '{ "eventName": "gameStarted", "userID": "ABCD1-4321a879b185fcb9c6ca27abc5387e914", "unityInstallationID": "Optional-Installation-ID", "unityPlayerID": "Optional-Authenticated-Player-ID", "sessionID": "4879bf37-8566-46ce-9f3b-bd18d6ac614e", "eventUUID": "374cc674-9785-4772-8cca-d7cdf517a590", "eventTimestamp": "2022-12-30 16:55:00.321 -08:00", "eventVersion": 1, "eventParams": { "platform": "WEB", "param1": "stringParam", "param2": true, "param3": 123 }}' \ "https://collect.analytics.unity3d.com/api/analytics/collect/v1/projects/{projectId}/environments/{environmentName}"
Response example
Generate a random unique userID
Generates a random unique userID. Subsequent requests will return a different value.
If you don’t have your own userID in your game, generating a Universally Unique Identifier (UUID) is the recommended way to create one. You’ll need to store the returned value locally on the client and reuse it for all future Collect calls from that specific client.