RudderStack 是一个开源的客户数据平台 (CDP)，可帮助企业收集、统一客户数据并将其发送到不同目的地。它为管理客户数据管道提供了一个集中式平台，使企业能够轻松地从网站、移动应用程序、服务器和云服务等各种来源收集数据。
Singular可通过Singular服务器到服务器（S2S）REST API从Rudderstack接收事件数据，用于iOS和安卓移动活动。这被称为"云模式 "目的地。下面的说明介绍了如何在 Rudderstack 中添加 Singular 目的地。
| 工程团队指南 | 工程团队 |
| 前提条件 | 本文假设您已经 将 Rudderstack iOS 或 Android SDK 集成到您的应用程序中。 |
要使用此集成，您必须使用 Rudderstack 的移动 SDK。此集成与非移动事件数据不兼容。不支持服务器或网络事件。
RudderStack 支持两种类型的跟踪事件，您可以通过 "云模式 "发送到 Singular：
- 会话事件
- 自定义事件
- 基本安装归因
- Google 安装推荐人归因
- 支持 SkAdNetwork 第 3 版（手动模式）
- 苹果搜索广告归因
- 自定义应用内事件跟踪
- 收入跟踪
- 自定义用户 ID
- 卸载跟踪
- SkAdNetwork 第 4 版支持
- 转换模型的 SkAdNetwork 管理模式
- META 安装推荐人归属
- 深度链接
- 有限数据共享支持
如果您需要Singular提供的 "完整特性功能 "的S2S支持，您必须独立于Rudderstack实现Singular S2S REST API。请点击此处查看服务器到服务器（S2S）集成指南。
开始使用
- 从您的RudderStack 面板，添加源。然后，从目的地列表中选择Singular。
- 为目的地指定一个名称，然后点击继续。
连接设置
要成功将 Singular 配置为目的地，需要配置以下设置：
-
API 密钥：在此输入 Singular 的"SDK 密钥"。这是必填字段。
获取 Singular"SDK 密钥 "，可在 Singular 控制面板"开发工具 > SDK 集成 > SDK 密钥 "下找到。
注意：对于 "云模式 "集成，您只需输入 API 密钥（SDK 密钥）值。
秘密 "留空。 -
会话事件名称：输入用作会话事件的事件名称。此设置仅适用于通过云模式发送事件。
RudderStack 会通过 Singular启动API 向 Singular 发送会话事件。
RudderStack 仅在仪表盘设置中指定的事件或以下三种生命周期事件之一时，才将其视为会话事件：
- 应用程序已安装
- 应用程序已打开
- 应用程序已更新
如果启用了生命周期事件跟踪，RudderStack 会自动跟踪上述三个生命周期事件。
- 使用设备模式发送事件： 使用 "云模式 "时，应禁用这些切换。使用 Android 或 iOS 平台时，可以启用此设置通过设备模式发送事件。然后，按照 Singular 设备模式指南了解将 Singular 添加到项目中的步骤。
会话事件要求
支持的会话事件映射
本节列出了 RudderStack 事件属性与相关 Singular 字段的映射。
下表列出了 RudderStack 为移动平台（安卓和iOS）自动捕获的属性映射：
| RudderStack 属性 | 奇异属性 | 存在 | 说明 |
|---|---|---|---|
context.os.name |
p |
需要 | 源平台（Android 或 iOS）。 |
context.app.namespace |
i |
必填 | 应用程序的软件包名称（Android）或软件包 ID（iOS）。 |
context.app.version |
app_v |
必填 | 应用程序版本。 |
context.ip / request_ip(按此顺序） |
ip |
必填 | 用户的 IP 地址。有关匿名 IP 的信息，请参阅下面的说明。 |
context.os.version |
ve |
需要 | 会话时的设备操作系统版本。 |
context.device.model |
mo |
必填 | 设备型号。该参数必须与 ma 参数一起使用。 |
context.device.manufacturer |
ma |
必填 | 设备硬件的品牌。该参数必须与 mo 参数一起使用。 |
context.locale |
lc |
必须填写 | 设备的 IETF 本地标记，使用双字母语言和国家代码，以下划线分隔。 |
context.device.id |
idfv |
必填 | 带破折号的大写原始IdentifierForVendor。仅适用于 iOS 应用程序。 |
context.device.id |
andi |
必须填写 | 原始Android ID（小写）。仅适用于 Android 应用程序，只有在设备上没有 Android 广告 ID 时才需要使用。 |
context.app.build |
bd |
必填 | 设备构建（URL 编码）。 |
context.device.adTrackingEnabled |
dnt |
必须填写 | 如果禁用了不跟踪（dnt），则输入 true（dnt=0），否则输入 false（dnt=1）。如果向 SDK 传递广告 ID，则会自动捕获此信息。 |
context.app.name |
n |
可选项 | 用户界面中显示的可读应用名称。 |
utime |
可选项 | 会话时间（UNIX 时间）。 | |
context.network.wifi |
c |
可选 | 连接类型（WiFi 或运营商）。 |
context.network.carrier |
cn |
可选 | 网络提供商的运营商名称。 |
下表列出了必须通过事件属性传递的属性映射：
这些属性不会在 SDK 中持久化，必须与每个事件一起传递。
| RudderStack 属性 | 奇异属性 | 存在 | 说明 |
|---|---|---|---|
properties.install_ref |
install_ref |
需要 | Google 安装推荐人信息。 |
properties.referring_application |
install_source |
必填 | Android 中的安装源软件包名称。使用getInitiatingPackageName()获取。 |
properties.install_receipt |
install_receipt |
必填 | 从安装中收到的收据。要检索该收据，请遵循iOS 安装收据指南。 |
properties.asid |
asid |
需要 | Android v12+ 设备的应用程序集 ID。 |
properties.url |
openui |
必须填写 | 如果应用程序是通过深度链接/通用链接打开的，则是已编码的深度链接 URL 的值。 |
context.device.attTrackingStatus |
att_authorization_status |
必须填写 | 应用程序跟踪透明度授权状态。 |
userId |
custom_user_id |
可选 | 通过标识调用传递的用户 ID。 |
properties.attribution_token |
attribution_token |
可选 | 用于归属 iOS 14.3 及以上版本的 Apple Search Ads。更多信息请点击此处。 |
properties.skan_conversion_value |
skan_conversion_value |
可选 | 会话通知时的最新 SkAdNetwork 值。 |
properties.skan_first_call_timestamp |
skan_first_call_timestamp |
可选 | 首次调用 SkAdNetwork API 的 UNIX 时间戳。 |
properties.skan_last_call_timestamp |
skan_last_call_timestamp |
可选 | 会话通知时最后一次调用 SkAdNetwork API 的 UNIX 时间戳。 |
properties.install |
install |
可选 | 安装标志。在应用程序安装后的首次会话中设置为 true，否则为 false。需要重新安装跟踪功能。 |
下表列出了必须通过事件属性只传递一次的属性的映射：
这些属性在 SDK 中持久存在，必须只传递一次。
| RudderStack 属性 | 单属性 | 存在 | 说明 |
|---|---|---|---|
context.device.token |
fcm |
可选 | Firebase 云消息设备令牌。在 Android 中卸载跟踪时需要使用该令牌。 |
context.device.token |
apns_token |
可选 | Apple 推送通知服务设备令牌。在 iOS 中，卸载跟踪需要此令牌。 |
context.device.advertisingId |
idfa |
必填 | 带破折号的大写原始广告 ID。仅适用于 iOS 应用程序。 |
context.device.advertisingId |
aifa |
必填 | 带破折号的小写原始广告 ID。仅适用于 Android 应用程序。 |
RudderStack 仅支持fcm映射设备令牌。
自定义事件要求
RudderStack 通过 Singular 的evt端点发送除会话事件以外的所有自定义事件。
支持的事件映射
本节列出了 RudderStack 事件属性到相关 Singular 字段的映射。
下表列出了 RudderStack 自动捕获的移动平台（安卓和iOS）的属性映射：
| RudderStack 属性 | 奇异属性 | 存在 | 说明 |
|---|---|---|---|
context.os.name |
p |
需要 | 源平台（Android 或 iOS）。 |
context.app.namespace |
i |
必填 | 应用程序的软件包名称（Android）或软件包 ID（iOS）。 |
context.ip / request_ip(顺序相同） |
ip |
必填 | 用户的 IP 地址。 |
context.device.advertisingId |
idfa |
必填 | 带破折号的大写原始IdentifierForVendor。仅适用于 iOS 应用程序。 |
context.device.advertisingId |
aifa |
必须填写 | 带破折号的小写原始广告 ID。仅适用于 Android 应用程序。 |
context.device.id |
idfv |
必填 | 带破折号的大写原始IdentifierForVendor。仅适用于 iOS 应用程序。 |
context.device.id |
andi |
必须填写 | 原始Android ID（小写）。仅适用于 Android 应用程序，只有在设备上没有 Android 广告 ID 时才需要使用。 |
context.os.version |
ve |
必填 | 会话时的设备操作系统版本。 |
utime |
可选 | 会话时间（UNIX 时间）。 |
在 Android 中，Singular 优先使用aifa而不是asid，在 iOS 中，优先使用asid而不是andi，优先使用idfa而不是idfv。
下表列出了必须通过事件属性传递的属性映射：
这些属性不会在 SDK 中持久化，必须与每个事件一起传递。
| RudderStack 属性 | 奇异属性 | 存在 | 说明 |
|---|---|---|---|
event |
n |
需要 | 事件名称。由用户定义。 |
context.device.attTrackingStatus |
att_authorization_status |
必填 | 应用程序跟踪透明度授权状态。 |
userId |
custom_user_id |
可选 | 通过标识调用传递的用户 ID。 |
properties.skan_conversion_value |
skan_conversion_value |
可选 | 会话通知时的最新 SkAdNetwork 值。 |
properties.skan_first_call_timestamp |
skan_first_call_timestamp |
可选 | 首次调用 SkAdNetwork API 的 UNIX 时间戳。 |
properties.skan_last_call_timestamp |
skan_last_call_timestamp |
可选 | 会话通知时最后一次调用 SkAdNetwork API 的 UNIX 时间戳。 |
properties.eventAttributes |
e |
可选 | JSON 格式的自定义事件属性。您需要在每个事件中传递这些属性，因为它们不会在 SDK 中持久化。 |
properties.is_revenue_event |
is_revenue_event |
可选 | 确定事件是否为收入事件。您需要在每个事件中通过属性传递这些属性，因为它们不会在 SDK 中持久化。 |
下表列出了收益事件特有的用户定义属性的映射：
| RudderStack 属性 | 单属性 | 存在 | 描述 |
|---|---|---|---|
properties.total/ properties.value / properties.revenue |
amt |
可选 | 货币金额。 |
properties.currency |
cur |
可选 | ISO 4217 三字母货币代码。应与 amt 参数一起使用。 |
properties.purchase_receipt |
purchase_receipt |
可选 | 购买后收到的收据。 |
properties.product_id/properties.sku |
purchase_product_id |
可选 | 产品 SKU 标识符。 |
properties.orderId / properties.purchase_transaction_id(按此顺序） |
purchase_transaction_id |
可选 | 交易标识符。 |
如果设置了value、 revenue 或 total属性中的任何一个，RudderStack 就会自动将该事件视为收入事件，除非is_revenue_event属性明确提到。
下面列出了自定义事件的一些重要注意事项：
- 对于安卓系统，RudderStack 从context.userAgent中获取用户代理；对于 iOS 系统，RudderStack 从事件属性中获取用户代理。
- RudderStack 会将自定义事件中传递的额外属性存储在 Singular 的e字段中。
测试
如何验证事件是否已成功发送到 Singular？
要验证事件是否成功发送到 Singular，可以使用 RudderStack 的Destination live events功能。
您也可以进入Singular 面板，按照以下步骤验证事件的交付：
按照这里的详细指南了解如何使用测试控制台
- 转到"开发工具 > 测试控制台"。
- 单击 "添加设备"，然后输入相关设备标识符：
- 你应该能看到发送到 Singular 的所有事件的实时日志：