Analytics REST API tutorial

Developers that don’t use Unity can access APIs via web endpoints or REST APIs. REST APIs provide more flexibility to automate your workflows using your favorite language and game development engine.

Analytics provides the following REST API: Analytics REST API Specificiation

Best practices

Generate a random unique userID

The REST API offers the following method for generating a random unique userID:

https://collect.analytics.unity3d.com/api/analytics/collect/v1/uuid

For more information, refer to the API documentation.

A userID is an ID that’s unique to a user. If you’re using Unity Gaming Services or another solution that generates a userID at the start of the user's lifecycle, use that userID to send to the Analytics REST API. If you don’t have your own userID in your game, it’s recommended to create a Universally Unique Identifier (UUID). You need to store the returned value locally on the client and reuse it for all future Collect calls from that specific client.

> WARNING: Don't change what you’re using.

When you have an ID, the user is identified by this value. However, there might be legal restrictions or limitations from licensing restrictions that prevent storing the apparent userID at third-party locations. A workaround is to create a hash of this ID and use it as a userID for the integration; this prevents storing the userID again.

Submit events to the Collect API endpoint

If you have events that can’t be sent through the SDK (for example, from a game server or for a non-Unity game), the Collect REST API records and sends events directly to Unity.

https://collect.analytics.unity3d.com/api/analytics/collect/v1/projects/{projectId}/environments/{environmentName}

The API Documentation can be found here.

The Collect REST API is the data collection endpoint where customers can submit their events to.

For more information, refer to the API documentation.

To record an event, make an HTTP POST to the Collect API. Your POST should be UTF-8 encoded. Set the HTTP request header to Content-Type: application/json and use one of the following URL formats:

To get the Environment name, go to the project’s Dashboard > Projects > Project Settings > Environments.

A set of Custom Events can be configured per environment. In the request body, specify a JSON document corresponding to the event type, described later.

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, see the Event Browser to see events coming in from your game.

Event payload

All events should be sent to the server in the body of the request as a JSON document. The document is different for every event type.

There are two formats that collect endpoints accept:

  1. A single-event format.
  2. A bulk event format.

1. A single-event format

{
    "eventName": "specific event code - eg. 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"
        ]
    }
}

Parameters that aren’t required don’t have to be included in the document. Omit these 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. A bulk event format

You can send multiple events in a single POST. This approach is preferable due to efficiencies in connection pooling. Keep the POST 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\"
      }
    }
}"

Sending ddnaForgetMe event

The ddnaForgetMe event is used to record that the player requests to opt-out and delete their data. UGS Analytics deletes the player data within seven days after receiving the payload.

{
     "eventName": "ddnaForgetMe",
     "eventTimestamp": "2020-01-01 12:00:00",
     "eventUUID": "foo",
     "eventVersion": 1,
     "sessionID": "foo",
     "userID": "foo",
     "eventParams": {
          "clientVersion": "foo",
          "sdkMethod": "foo"
     }
}