针对PC个人电脑和游戏终端集成指南

关注
Avatar
Jared Ornstead
Updated

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

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

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

集成概念

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

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

用户隐私

为了保护用户隐私，Singular 建议游戏开发者为最终用户提供一个选项，让他们选择是否向 Singular 发送游戏事件数据。

身份验证

所有对Singular PC和控制台S2S API的请求都需要在 "a="参数中发送SDK密钥。您可以在 Singular 面板的 "开发工具 -> SDK 集成 > SDK 密钥 "中找到您的 Singular 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
steamos		 steam
epicgamestore
microsoftstore
gog
humblestore
selfdistributed
xbox xbox_one
xbox_360
xbox_series_s
xbox_series_x		 xbox
playstation playstation_3
playstation_4
playstation_5		 playstation
nintendo nintendo_switch nintendo
metaquest metaquest
metaquest_2
metaquest_pro		 metaquest

游戏标识符

为了让 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"）。