Record events with the REST API

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.

WARNING: You must not record or upload events through the REST API unless you have appropriate consent from the player under relevant data privacy legislation. For more information, see the privacy overview.

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"
      }
    }
  ]
}

Note: keep the events inside a bulk event list in the order they happened.

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:

HeaderDescription
PIPL_CONSENTThe 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_EXPORTThe 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 valueDescription
no_consentIndicates that no consent was given for this request via the PIPL_CONSENT request header.
no_exportIndicates 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 nameDescription
userIDEvery 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.
sessionIDThe 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.
eventUUIDAn 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.
eventTimestampAn 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.

Note: When using the REST API you must also provide a mechanism for players to request data deletion. For more information, see the request data deletion with the REST API tutorial and the data privacy overview.