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.

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:

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.

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#

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.