Record events with the REST API
Record events through the REST API to track data from non-Unity applications.
読み終わるまでの所要時間 5 分最終更新 2日前
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.
POSTPOSTContent-Type: application/jsonhttps://collect.analytics.unity3d.com/api/analytics/collect/v1/projects/{projectId}/environments/{environmentName}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
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.{ "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" ] }}
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 aneventList{ "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 aPIPL_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 |
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 |
Response codes
If the status code is204 No Content204 No ContentFurther 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.