Analytics REST API

Send Analytics events from non-Unity games through the REST API.

阅读时间6 分钟

最后更新于 3 天前

不使用 Unity 的开发者可以通过 Web 终端或 REST API 访问 API。REST API 提供更大的灵活性，让您可以利用喜欢的语言和游戏开发引擎来自动执行工作流程。 Analytics 提供以下 REST API：

Analytics

最佳实践

生成随机且具有唯一性的 userID

REST API 提供以下方法来生成随机且具有唯一性的 userID：

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

请参阅此处的 API 文档。 userID 是用户唯一的 ID。如果您正在使用 Unity Gaming Services（Unity 游戏服务）或其他在用户生命周期开始时生成 userID 的解决方案，请使用该 userID 发送到 Analytics REST API。如果您在游戏中没有自己的 userID，建议生成通用唯一标识符 (UUID) 来创建一个。您需要将返回的值存储在客户端本地，并将其重复用于来自该特定客户端的所有未来 Collect 调用。不要更改您所使用的内容。拥有 ID 后，即可通过此值来标识用户。但是，可能会有法律限制或许可限制禁止将明显的 userID 存储在第三方。解决这种问题的变通方法通常是创建此 ID 的哈希并将其用作集成 userID；这样可以避免需要再次存储 userID。

将事件提交到 Collect API 终端

如果无法通过 SDK 发送事件（例如，从游戏服务器发送的事件，或非 Unity 游戏的事件），则 Collect REST API 会记录事件并将其直接发送到 Unity。

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

请参阅此处提供的 API 文档。要记录事件，请对 Collect API 执行 HTTP POST 以记录事件。此 POST 应采用 UTF-8 编码。请将 HTTP 请求标头设置为

Content-Type: application/json

，并使用以下 URL 格式之一：要获取环境名称，请转到项目的 Dashboard（后台）> Projects（项目）> Project Settings（项目设置）> Environments（环境）。每个环境可以配置一组自定义事件。在请求正文中，指定与事件类型对应的 JSON 文档，如下文所述。如果状态代码为 204 No Content（204 无内容），表示服务器已成功接收事件，但服务器不想发回任何内容。如果状态代码是 204 No Content（204 无内容）之外的任何其他代码，表示处理请求时出错。状态代码和消息将描述遇到的问题，例如：400 Bad Request –“Custom Event Code not recognized”（400 错误请求 –“无法识别自定义事件代码”）。请查看此处的详细信息。要验证事件是否已由我们的服务处理，请参阅 Event Browser（事件浏览器）以查看来自您游戏的事件。

事件有效负载

所有事件都应在请求正文中以 JSON 文档的形式发送到服务器。每个事件类型的文档都不同。 Collect 终端接受两种格式：

单一事件格式
批量事件格式

1.单一事件格式


{    "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"        ]    }}

不需要的参数不必包含在文档中，应忽略它们，而不是发送空参数或 null 参数。任何时间戳早于 31 天或晚于未来 24 小时的事件都将被拒绝，因为它们超出了有效边界。

2.批量事件格式

您可以在单次 POST 中发送多个事件。由于连接池具有高效率，因此这是一种较好的做法。应将 POST 长度保持在 5MB 以下；超出此长度的所有内容都可能被拒绝。每个事件的格式保持不变，但以包含各个事件的 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"      }    }  ]}

注意：批量事件列表中的事件应按其发生的顺序排列。

发送 ddnaForgetMe 事件

ddnaForgetMe 事件用于记录玩家请求退出数据收集并删除其数据。UGS Analytics 在收到有效负载后的七天内删除玩家数据。如果您使用 REST API，但没有自己的 UUID 生成器，则可以使用我们提供的 UUID 生成功能。如果您发送了此事件，您还必须停止发送用户的数据，否则服务将再次收集用户的数据。


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

发送 PIPL 同意

中国新的数据隐私法《个人信息保护法》于 2021 年 11 月 1 日生效。个人信息是指可以识别个人身份（例如姓名或地址）并以电子或其他方式存储的数据。敏感的个人信息是指生物特征、性别认同、宗教信仰、病史、财务状况以及十四周岁以下未成年人的任何个人信息。 PIPL 是一项基于“未明确同意就是拒绝”原则的法规。我们的 Collect 终端使用 HTTP 标头来标识位于中国的用户的同意状态。应在适当的情况下对要收集的所有 HTTP 请求使用以下标头：

标头	描述
PIPL_CONSENT	此标头的存在将表明玩家已同意数据收集。不同意的玩家不应在请求中设置此标头。标头的值无关紧要。
PIPL_EXPORT	此标头的存在将表明玩家已同意将其数据发送到中国境外进行处理。不同意的玩家不应在请求中设置此标头。标头的值无关紧要。

响应标头任何符合 PIPL 要求的 HTTP 请求都应在响应中包含 PIPL_STATUS 标头，以便通过确认后端采取的操作来帮助进行测试。

标头值	描述
no_consent	指示未通过 PIPL_CONSENT 请求标头对此请求给予同意。
no_export	指示对于此请求未同意通过 PIPL_EXPORT 请求标头导出数据。

示例代码：


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\"      }    }}"

文档

引擎

服务

增长

工业

支持

Analytics