Analytics REST API#

Developers that do not 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

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

See the API Documentation here.

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, generating a Universally Unique Identifier (UUID) is recommended 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. Do not change what you’re using.

When you have an ID, the user can be identified by this value. However, there might be legal restrictions or limitations due to licensing restrictions that prevent storing the apparent userID at third-party. Creating a hash of this ID and using it as a userID for the integration is generally a workaround to this problem; this prevents having to store 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.

To record an event, make a HTTP POST to the Collect API to record an event. 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, as described later.

If the status code is 204 No Content, the event has been successfully received by the server and there’s nothing that 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 will describe the problem encountered. For example: 400 Bad Request – “Custom Event Code not recognized”. See details here.

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 which 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: The events inside a bulk event list should be maintained in the order they occurred.

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.

We offer the ability to generate the UUID if you use the REST API but don't have your own UUID generator.

If you sent this event, you must also stop sending data for the user, or the service collects data for the user again.

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

Send PIPL consent#

China’s new data privacy law - Personal Information Protection Law - came into effect on November 1st 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 fourteen 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 requests which fall under the PIPL requirements should include a PIPL_STATUS header in the response to aid with testing by acknowledging 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\": \"UA1_SDKLESS\",
      \"userLocale\": \"aa_BB\"
      }
    }
}"