Documentation

Support

Analytics

Analytics

Record events with the REST API

Record events through the REST API to track data from non-Unity applications.
Read time 5 minutesLast updated a day ago
If you have a non-Unity game or wish to send events from a server, you can still use the REST API to send events directly to Unity. To record an event, make an HTTP 
POST
request to the Collect API. Your 
POST
should be UTF-8 encoded. Set the HTTP request header to 
Content-Type: application/json
and use the following URL: 
https://collect.analytics.unity3d.com/api/analytics/collect/v1/projects/{projectId}/environments/{environmentName}
 To get the environment name, go to the project's Dashboard > Projects > Project Settings > Environments.

Request payload

All events should be sent to the server in the body of the request as JSON documents. The document should match the structure of an event schema as defined in the Event Manager. There are two formats that Collect endpoints accept:
  1. The single event format
  2. The bulk event format

1. Single event format

{    "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": "yyyy-mm-dd hh:mm:ss.SSS",    "eventParams": {        "platform": "WEB",        "param1": "stringParam",        "param2": true,        "param3": 1234,        "param4": [            "a",            "b",            "c"        ]    }}
Omit parameters that aren't required rather than sending empty or null parameters. Any event with a timestamp older than 31 days ago or newer than 24 hours in the future is rejected as they are outside valid boundaries.

2. Bulk event format

You can send multiple events in a single request. This approach is preferable due to efficiencies in connection pooling. Keep the POST body length below 5MB; anything above might be rejected. The format of each individual event remains the same, but they’re represented in an 
eventList
array containing individual events. For example: 
{  "eventList": [    {      "eventName": "clientDevice",      "userID": "e44db226-5b29-11ec-819e-dca6325ca17a",      "sessionID": "8ebb023e-6edc-11ec-a519-dca6325ca17a",      "eventUUID": "02ff8461-8d1d-46bb-94f3-51c81e63b371",      "eventVersion": 1,      "eventTimestamp": "2022-01-06 03:29:17.030",	  "eventParams": {        "platform": "ANDROID",        "userCountry": "US",        "clientVersion": "2.0.3",        "sdkMethod": "com.unity.services.analytics.Events.Startup"      }    },    {      "eventName": "gameStarted",      "userID": "e44db226-5b29-11ec-819e-dca6325ca17a",      "sessionID": "8ebb023e-6edc-11ec-a519-dca6325ca17a",      "eventUUID": "a379af6c-4fac-4449-b6c7-925ee87b446e",      "eventVersion": 1,      "eventTimestamp": "2022-01-06 03:29:17.040",      "eventParams": {        "platform": "ANDROID",        "userCountry": "US",        "clientVersion": "2.0.3",        "sdkMethod": "com.unity.services.analytics.Events.Startup",        "userLocale": "en_US"      }    }  ]}

Sending PIPL consents

China's new data privacy law, the Personal Information Protection Law (PIPL) came into effect on November 1, 2021. Personal information is data that can identify a person, such as name or address, and is stored electronically or otherwise. Sensitive personal information refers to biometrics, gender identity, religious beliefs, medical history, finance, and any personal information of minors under 14 years. PIPL is an opt-in based legislation. Our Collect endpoint uses HTTP headers to identify consent from users located in China. The following headers should be used where appropriate on all HTTP requests to collect:

Header

Description

PIPL_CONSENT
The presence of this header indicates the player has granted consent to data collection. Players who don't consent are advised not to have this header set on requests. The value of the header doesn't matter.
PIPL_EXPORT
The presence of this header indicates the player has granted consent to their data being sent out of China for processing. Players who don't consent are advised not to have this header set on requests. The value of the header doesn't matter.

Response headers

Any HTTP request that falls under the PIPL requirements should include a 
PIPL_STATUS
header in the response to test and acknowledge actions taken by the backend.

Header value

Description

no_consent
Indicates that no consent was given for this request via the 
PIPL_CONSENT
request header.
no_export
Indicates that no consent was given for this request to export data via the 
PIPL_EXPORT
request header.
Sample code: 
curl -v --location --request POST "https://collect.analytics.unity3d.com/collect/api/project/{id}/production" \--header 'Content-Type: application/json' \--header 'PIPL_CONSENT: true' \--header 'PIPL_EXPORT: true' \--data-raw "{    \"userID\": \"some-id\",    \"eventName\": \"gameStarted\",    \"eventVersion\": 1,    \"eventUUID\":\"some-uuid\",    \"sessionID\": \"sessionID\",    \"eventParams\": {      \"platform\": \"ANDROID\",      \"clientVersion\": \"testVersion\",      \"sdkMethod\": \"na\",      \"userLocale\": \"aa_BB\"      }    }}"

Important fields

Field name

Description

userID
Every event must contain a user ID, which is a unique string that identifies the player and is consistent across their subsequent play sessions. For more information, see the tutorial on how to generate a unique user ID with the REST API.
sessionID
The session ID is an optional parameter on all events. It should contain a unique string value that persists for the duration of each gameplay session and regenerates with each new gameplay session. The session ID should be sent with every event the player triggers in their session. The Unity Analytics platform then uses the session ID to calculate data, such as the number of sessions each player plays and the length of each 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 session ID. 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. Typical examples of ghost events would be attribution events or transactional information originating from third party services.
eventUUID
An optional parameter which should be unique for each event. Adding the 
eventUUID
will prevent the event being inserted twice accidentally, for example if a network time-out occurs even though the event has been processed.
eventTimestamp
An optional parameter. If the 
eventTimestamp
parameter is missing, the server upon receipt of the event will infer the timestamp based on the time the event was received. The date format should be 
yyyy-MM-dd HH:mm:ss.SSS ±hh:mm
, where the 
±hh:mm
must be included to indicate a timezone offset from UTC, or 
+00:00
to indicate no offset. For example, 
2021-12-30 16:55:00.321 -08:00
.
The order of the parameters doesn't matter for JSON. Omit parameters which aren't required rather than sending empty or null parameters. Any event with a timestamp older than 31 days ago or newer than 24 hours in the future will be rejected as they are outside valid boundaries.

Response codes

If the status code is 
204 No Content
, the event is successfully received by the server and there's nothing the server wants to send back. If the status code is anything other than 
204 No Content
, there was an error serving the request. The status code and the message describes the problem. For example: 400 Bad Request – "Custom Event Code not recognized". To learn more, refer to Analytics Collect API. To verify whether the event has been processed by our service, visit the Event Browser to see events coming in from your game.

Further reading

For more information about the REST API, refer to the API documentation.