个人电脑和控制台游戏集成指南

关注
Avatar
Jared Ornstead
Updated
文档

PC 和游戏机游戏归因是一项企业功能。 如需进一步了解该功能，请阅读我们的PC和主机游戏归因常见问题，或联系您的客户成功经理。

Singular提供REST API，可用于向Singular报告所有PC和主机游戏转换数据，以便进行分析和归因。

本指南介绍如何与 Singular 建立 PC 和游戏机 S2S 集成，并实现各种可选功能。

集成概念

本节详细介绍了对于实现功能完善的 PC 和控制台 S2S 集成非常重要的总体概念。

有关 S2S API 端点、其参数和调用示例的完整列表，请参阅《PC 和控制台 S2S 端点参考》。

用户隐私

为了保护用户隐私，Singular 建议游戏开发者为最终用户提供选择加入或退出跟踪的选项。 根据企业处理用户数据的要求，您可以

  • 选择退出时，不向Singular发送游戏事件数据
  • 向 Singular 发送游戏事件数据，但包括用户的选择加入和选择退出同意选项。在这种情况下，通过data_sharing_options参数中的 "限制数据共享 "值实现并传递此同意标志。

Singular会在"用户隐私回传"中使用 "限制数据共享"，并将此信息传递给需要的合作伙伴，以遵守相关法规。更多信息，请参阅"用户隐私和限制数据共享"。

身份验证

所有对Singular PC & Console S2S API的请求都需要在 "a="参数中发送SDK密钥。您的Singular SDK密钥可以在Singular仪表板的"开发工具-> SDK集成> SDK密钥"中找到。

警告：请勿使用 "开发工具 -> API 密钥 "中的 Singular "API 密钥"。 API 密钥 "单独用于Singular 的报告 API。

支持的平台、游戏系统和商店

Singular 中的 "平台 "定义为用户玩游戏的 "平台"，必须在所有 S2S API 请求中通过"p="参数传递。 支持的 "平台 "值的封闭列表如下：

  • pc
  • xbox
  • playstation
  • nintendo
  • metaquest

除 "平台 "外，还应在"os="和 "install_source="参数中分别传递 "操作系统/游戏系统 "和 "商店"。支持自定义值，但 Singular 建议按平台使用以下值：

平台
(p=)		 操作系统/游戏系统
(os=)
 存储
(install_source=)
pc
 Windows
linux
macos
蒸汽		 蒸汽
史诗级商城
微软商店
gog
humblestore
自发行
xbox xbox_one
xbox_360
xbox_s 系列
xbox_series_x		 xbox
游戏机 playstation_3
游戏机_4
游戏机 5		 游戏机
任天堂 任天堂开关 任天堂
元任务 元任务
metaquest_2
metaquest_pro		 元任务

游戏标识符

为了让 Singular 将游戏事件与游戏关联起来，必须在每次请求的"i="参数中传递游戏标识符。

  • 可以支持任何值，但 Singular 建议使用反向 DNS 符号传递该值（即com.singular.game）
  • 如果您的游戏可在多个平台上运行，则要求在支持的平台上对同一游戏使用相同的游戏标识符（例如，p=pc&i=com.singular.game、p=xbox&i=com.singular.game、p=playstation&i=com.singular.game）
  • 为了让Singular正确地将游戏转化归因于通过网站登陆页面进行的网络营销活动，您的Singular网络集成的 "产品ID "也必须与游戏标识符值相匹配。

识别唯一的游戏安装

为使 Singular 能在多个游戏会话中关联同一游戏安装的游戏事件，必须在每次请求的"sdid="参数中传递安装/设备标识符。

  • 推荐的 UUID（第 4 版）格式
  • 该值应在游戏首次启动（安装）时由游戏/服务器生成，并在游戏安装的整个过程中持续存在。

匹配 ID（可选）

如果您的游戏网络推广活动将用户引向网络登陆页面，并且您可以利用 "匹配 ID "进行网站 -> PC/Console 游戏归因，您可以选择在"match_id="参数中传递 "匹配 ID"，以提高归因的准确性。有关 PC 和控制台归因的更多信息，请参阅我们的常见问题。

  • 要使安装归因使用 "匹配 ID"，必须在用户首次启动游戏时传递该 ID。
  • "匹配 ID "必须与您的Singular 网页 SDK 实现中的用户值一致。

重要提示：使用匹配 ID 进行归属是一项高级功能。实施前请咨询您的 Singular 解决方案工程师。

报告游戏启动

在 PC 和控制台集成中需要向 Singular 报告所有游戏会话，并希望每次启动游戏时都发送游戏会话。

要将游戏会话通知 Singular，请调用会话通知端点。

会话通知允许 Singular 做几件事：

  • 如果这是唯一安装（参见识别唯一游戏安装）后的第一个游戏会话，Singular 会识别新安装并触发安装归属过程。
  • (即将推出）如果游戏会话符合重新参与会话的条件，Singular 会触发重新参与归因流程（在重新参与常见问题中了解更多信息）。
  • 否则，Singular 会将其标记为游戏会话，用于跟踪用户活动和留存。

提示： 在收集数据以报告游戏会话时，请务必等待异步函数返回并处理各种功能。例如

  • 当使用匹配 ID 改进归属匹配时，重要的是只有在匹配 ID 可能可用后才报告第一个游戏会话。请参阅 "匹配 ID"。
  • 如果您的游戏提供了一种选择加入 Singular 营销和游戏分析的方式，那么在报告游戏会话之前，一定要先征得同意。请参阅用户隐私。

报告游戏内事件

活动

Singular可以收集游戏内事件的数据，帮助分析营销活动的效果。事件可以包括任何用户互动，从登录和注册到游戏中的等级提升。

在实施与 Singular 的 S2S 集成之前，您应该有一份贵组织希望跟踪的事件列表（请参阅定义游戏内事件）。

要在游戏中发生事件时通知 Singular，请调用事件通知端点。 您在调用中包含的事件名称将在 Singular 报告、导出和回传中被识别。

注意事项：

  • Singular 建议使用Singular 的标准事件和属性命名约定传递事件。使用标准事件可以简化映射，并在集成中与合作伙伴的标准事件兼容。
  • Singular 建议使用英文传递自定义事件名称和属性，以便与第三方合作伙伴和分析解决方案兼容。
  • 事件名称限制为 32 个 ASCII 字符。对于非 ASCII 字符，转换为 UTF-8 后限制为 32 字节。
  • 事件属性和值限制为 500 个 ASCII 字符。

收入

Singular可以收集通过游戏获得的收入数据，以帮助分析活动的表现和投资回报率。Singular会通过报告、日志导出和回帖等方式向您提供这些数据。

要跟踪收入事件，请使用与所有事件相同的事件通知端点，但要添加以下信息：

  • is_revenue_event=true：这会将事件标记为收入事件。如果事件名称为"__iap__"或金额大于零，可以跳过此参数。
  • 收入金额（例如，"amt=1.99"）。
  • 货币（使用 ISO 4217货币代码，如"cur=USD"）。