Record events with the REST API
Record events through the REST API to track data from non-Unity applications.
読み終わるまでの所要時間 5 分最終更新 8ヶ月前
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.
注意
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 request to the Collect API. Your should be UTF-8 encoded. Set the HTTP request header to and use the following URL:
POSTPOSTContent-Type: application/jsonhttps://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:
- The single event format
- 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 array containing individual events. For example:
eventList{ "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" } } ]}
注
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:
Header | Description |
|---|---|
| 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. |
| 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 header in the response to test and acknowledge actions taken by the backend.
PIPL_STATUSHeader value | Description |
|---|---|
| Indicates that no consent was given for this request via the |
| Indicates that no consent was given for this request to export data via the |
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 |
|---|---|
| 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. |
| 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 |
| An optional parameter which should be unique for each event. Adding the |
| An optional parameter. If the |
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 , the event is successfully received by the server and there's nothing the server wants to send back.
204 No ContentIf the status code is anything other than , 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.
204 No ContentTo 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.
注
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.