RudderStack 是一个开源客户数据平台（CDP） 可帮助企业收集、统一并将客户数据路由到各种目的地。它提供了一个用于管理客户数据管道的集中式平台，使组织能够轻松地从网站、移动应用、服务器和云服务等各种来源收集数据。

Singular 可以通过 Singular Server-to-Server (S2S) REST API 接收来自 Rudderstack 的 iOS 和 Android 移动端活动事件数据。这被称为 “Cloud-Mode” 目的地 。以下说明演示了如何在 Rudderstack 中添加 Singular 目的地。

适用指南	工程团队
前提条件	本文假设您已经将 Rudderstack iOS 或 Android SDK 集成到您的应用中。

要使用此集成，您必须使用 Rudderstack 的移动 SDK。 此集成不兼容非移动端事件数据。不支持服务器或网页事件。

RudderStack 支持两种可通过 “Cloud-Mode” 发送给 Singular 的 track 事件类型：

会话事件
自定义事件

支持的功能

基础安装归因
Google Install Referrer 归因
SkAdNetwork 第 3 版支持（手动模式）
Apple Search Ads 归因
自定义应用内事件跟踪
收入跟踪
自定义用户 ID
卸载跟踪
Limited Data Sharing（用户同意）支持
通过 API v2 支持 Singular Device ID (SDID)

不支持的功能

SkAdNetwork 第 4 版支持
用于转化模型的 SkAdNetwork 托管模式
META Install Referrer 归因
深度链接

如果您需要 S2S 支持 Singular 提供的“完整功能”，则必须独立于 Rudderstack 实现 Singular S2S REST API。请参阅 Server-to-Server (S2S) 集成指南 此处。

Singular Device ID (SDID) 与 API 版本

RudderStack 使用的 Singular API 版本取决于事件中存在的标识符字段：

如果事件中存在 Singular Device ID (SDID) ，RudderStack 会自动使用 Singular API v2 并忽略传统的平台专属标识符（ idfa 、 andi 、 idfv 、 aifa ）。
否则，RudderStack 会回退到平台专属标识符，并使用 Singular API v1 发送事件。

要发送 Singular Device ID（以及可选的数据共享同意），请在事件的 integrations.Singular 对象中包含 singularDeviceId 和 limitDataSharing ：

rudderanalytics.track(
  "Order Completed", {
    revenue: 30,
    currency: "USD"
  }, {
    integrations: {
      Singular: {
        singularDeviceId: "SINGULAR_DEVICE_ID",
        limitDataSharing: true  // optional
      }
    }
  }
);

入门

在您的 RudderStack 控制台中，添加数据源。然后，从目的地列表中选择 Singular 。
为您的目的地指定一个名称，然后单击 Continue 。

连接设置

要成功将 Singular 配置为目的地，您需要配置以下设置：

API Key： 在此处输入您的 Singular “SDK Key” 。此为必填字段。
获取您的 Singular “SDK KEY” ，可在 Singular Dashboard 中的 “Developer Tools > SDK Integration > SDK Keys” 下找到。

注意： 对于 “Cloud-Mode” 集成，您将 仅输入 API Key（SDK Key）值 。
请将 “Secret” 留空。
Session Event Name： 输入要用作会话事件的事件名称。此设置仅适用于通过 cloud mode 发送事件。
RudderStack 通过 Singular launch API 将会话事件发送给 Singular。
只有当某个事件在控制台设置中被指定，或者它是以下三个生命周期事件之一时，RudderStack 才会将其视为会话事件：
- Application Installed
- Application Opened
- Application Updated
如果启用了生命周期事件跟踪，RudderStack 会自动跟踪上述三个生命周期事件。
Use device mode to send events： 使用 “Cloud Mode” 时 应禁用 这些开关。使用 Android 或 iOS 平台时，您可以启用此设置以通过 device mode 发送事件。然后，按照 Singular Device Mode 指南中的步骤将 Singular 添加到您的项目中。
客户端事件过滤： 指定哪些事件应被阻止或允许发送到 Singular。有关更多信息，请参阅 Client-side Events Filtering 指南。
同意管理设置： 通过从下拉菜单中选择同意管理提供商并输入相关的同意类别 ID，为该来源配置同意管理设置。有关更多信息，请参阅 Consent Management in RudderStack 。

Unity SDK 设置

以下设置适用于使用 Unity 作为来源时：

设置	说明
Match ID mapping	使用此设置将 Singular 的 match ID 映射到以下事件字段之一： `context.device.advertisingId` 或 `properties.match_id`.

会话事件要求

支持的 SESSION 事件映射

Rudderstack 移动 SDK 自动捕获的属性

本节列出了 RudderStack 事件属性到相关 Singular 字段的映射。

下表列出了 RudderStack 为移动平台（ Android 和 iOS ）自动捕获的属性映射：

RudderStack 属性	Singular 属性	是否必需	说明
context.os.name	p	必需	来源平台（Android 或 iOS）。
context.app.namespace	i	必需	您应用的包名（Android）或 bundle 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 应用，并且当广告 ID (aifa) 和 App Set ID (asid) 均不存在时为必需。有关更多信息，请参阅下面的 FAQ。
context.app.build	bd	必需	设备构建版本（URL 编码）。
context.device.adTrackingEnabled	dnt	必需	如果 do not track (dnt) 已禁用 (dnt=0)，则传递 true，否则传递 false (dnt=1)。如果您将广告 ID 传递给 SDK，则会自动捕获此值。
context.app.name	n	可选	在 UI 中显示的可读应用名称。
timestamp / originalTimestamp	utime	可选	会话时间（UNIX 时间）。
context.network.wifi	c	可选	连接类型（WiFi 或运营商）。
context.network.carrier	cn	可选	互联网提供商的运营商名称。
integrations.Singular.limitDataSharing	data_sharing_options.limit_data_sharing	可选	JSON URL 编码的用户数据共享同意。它必须持久保存并在所有后续事件请求中传递。

要匿名化您的 IP，您可以在 context.ip 字段中发送一个占位 IP。RudderStack 会将其用作 IP 地址，而不是从后端自动捕获。对于移动 SDK，您可以在通过 cloud mode 发送事件时，利用 Transformations 功能来实现这一点。

必须通过事件属性传递的属性

下表列出了 必须通过事件属性传递的属性映射：

这些属性不会在 SDK 中持久保存，必须随每个事件一起传递。

RudderStack 属性	Singular 属性	是否必需	说明
properties.install_ref	install_ref	必需	Google Install Referrer 信息。
properties.referring_application	install_source	必需	Android 中的安装来源包名。使用 getInitiatingPackageName() 来获取此值。
properties.install_receipt	install_receipt	必需	从安装中收到的收据。要获取此值，请遵循 iOS Install Receipt 指南。
properties.asid	asid	必需	适用于 Android v12+ 设备的 App Set ID。当广告 ID (aifa) 和 Android ID (andi) 均不存在时为必需。有关更多信息，请参阅下面的 FAQ。
properties.url	openui	必需	如果应用是通过深度链接/通用链接打开的，则为编码后的深度链接 URL 的值。
context.device.attTrackingStatus	att_authorization_status	必需	App Tracking Transparency 授权状态。
userId	custom_user_id	可选	通过 identify 调用传递的用户 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。重装跟踪功能需要此项。
properties.install_time / timestamp / originalTimestamp	install_time	可选	安装时间（UNIX 时间）。
properties.update_time / timestamp / originalTimestamp	update_time	可选	更新时间（UNIX 时间）。

只需通过事件属性传递一次的属性：

下表列出了 只需通过事件属性传递一次的属性映射：

这些属性会在 SDK 中持久保存，只需传递一次。

RudderStack 属性	Singular 属性	是否必需	说明
context.device.token	fcm	可选	Firebase Cloud Messaging 设备令牌。Android 上的卸载跟踪需要此项。
context.device.token	apns_token	可选	Apple Push Notification Service 设备令牌。iOS 上的卸载跟踪需要此项。
context.device.advertisingId	idfa	必需	原始的广告 ID ，大写并带连字符。仅适用于 iOS 应用。
context.device.advertisingId	aifa	必需	这是小写的原始广告 ID ，带连字符。仅适用于 Android 应用。当 App Set ID (asid) 和 Android ID (andi) 均不存在时为必需。有关更多信息，请参阅下面的 FAQ。

有关设置设备令牌的更多信息，请参阅相关的 SDK 文档：

Android
iOS

RudderStack 仅支持 fcm 用于映射设备令牌。

自定义事件要求

RudderStack 通过 Singular 的 evt 端点，将会话事件以外的所有事件作为自定义事件发送。

支持的 EVENT 映射

Rudderstack 移动 SDK 自动捕获的属性

本节列出了 RudderStack 事件属性到相关 Singular 字段的映射。

下表列出了 RudderStack 为移动平台（ Android 和 iOS ）自动捕获的属性映射：

RudderStack 属性	Singular 属性	是否必需	说明
context.os.name	p	必需	来源平台（Android 或 iOS）。
context.app.namespace	i	必需	您应用的包名（Android）或 bundle ID（iOS）。
context.ip / request_ip （按相同顺序）	ip	必需	用户的 IP 地址。
context.device.advertisingId	idfa	必需	原始的 IdentifierForVendor ，大写并带连字符。仅适用于 iOS 应用。
context.device.advertisingId	aifa	必需	这是小写的原始广告 ID ，带连字符。仅适用于 Android 应用。当 App Set ID (asid) 和 Android ID (andi) 均不存在时为必需。有关更多信息，请参阅下面的 FAQ。
context.device.id	idfv	必需	原始的 IdentifierForVendor ，大写并带连字符。仅适用于 iOS 应用。
context.device.id	andi	必需	原始的 Android ID ，小写。仅适用于 Android 应用，并且当广告 ID (aifa) 和 App Set ID (asid) 均不存在时为必需。有关更多信息，请参阅下面的 FAQ。
context.os.version	ve	必需	会话时的设备操作系统版本。
timestamp / originalTimestamp	utime	可选	会话时间（UNIX 时间）。
integrations.Singular.limitDataSharing	data_sharing_options.limit_data_sharing	可选	JSON URL 编码的用户数据共享同意。它必须持久保存并在所有后续事件请求中传递。

Singular 优先使用 aifa 而非 asid ，优先使用 asid 而非 andi （在 Android 中），并优先使用 idfa 而非 idfv （在 iOS 中）。

必须通过事件属性传递的属性

下表列出了 必须通过事件属性传递的属性映射：

这些属性不会在 SDK 中持久保存，必须随每个事件一起传递。

RudderStack 属性	Singular 属性	是否必需	说明
event	n	必需	事件名称。这是用户自定义的。
context.device.attTrackingStatus	att_authorization_status	必需	App Tracking Transparency 授权状态。
userId	custom_user_id	可选	通过 identify 调用传递的用户 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	可选	用于确定某个事件是否为收入事件。您需要随每个事件通过 properties 传递此项，因为它不会在 SDK 中持久保存。
properties.receipt_signature	receipt_signature	可选	收据签名。

收入事件专用的用户自定义属性

下表列出了 收入事件专用的用户自定义属性映射：

RudderStack 属性	Singular 属性	是否必需	说明
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 属性中的任何一个，除非通过 is_revenue_event 属性明确指定，否则 RudderStack 会自动将该事件视为收入事件。

以下列出了自定义事件的几个重要注意事项：

对于 Android，RudderStack 从 context.userAgent 获取 user agent；对于 iOS，则从事件属性中获取。
RudderStack 将自定义事件中传递的额外属性存储在 Singular 的 e 字段中。

测试

如何验证事件是否已成功传递给 Singular？

要验证事件是否已成功传递给 Singular，您可以使用 RudderStack 的 Destination live events 功能。

您也可以通过访问您的 Singular dashboard 并遵循以下步骤来验证事件传递：

请遵循此处的详细指南，了解如何使用 Testing Console

前往 “Developer Tools > Testing Console” 。
单击 Add Device ，然后输入相关的设备标识符：
您应该能够看到发送给 Singular 的所有事件的实时日志：

FAQ

Android 需要哪些设备 ID 属性？

对于 Android 请求，Singular 需要以下属性之一，按此优先顺序：

```
aifa
```
```
asid
```
```
andi
```

如果它们都不可用，您必须发送至少一个带有空值的属性（而不是 null 或 undefined）。如果您全部发送，RudderStack 会根据 Google 的数据政策丢弃 andi 属性。

Rudderstack - Singular目的地（云模式）