文档

RudderStack 是一个开源的客户数据平台 (CDP)，可帮助企业收集、统一客户数据并将其发送到不同目的地。它为管理客户数据管道提供了一个集中式平台，使企业能够轻松地从网站、移动应用程序、服务器和云服务等各种来源收集数据。

Singular SDK 可作为 Rudderstack 的插件使用，被称为"设备模式 "目的地（Device-Mode Destination）。下面的说明介绍了如何在 Rudderstack 中添加 Singular 目的地。

请注意，此集成由 Rudderstack 构建和维护。如果在实施过程中出现问题，请咨询 Rudderstack。

工程团队指南	工程团队
前提条件	本文假设您的应用程序中已经集成了 Rudderstack iOS、Android、React Native 或 Cordova SDK。有关设备模式和移动 SDK 的更多详情，请参阅 Rudderstack 文档。

要使用此集成，您必须使用 Rudderstack 的以下移动 SDK：iOS（原生 Obj-C 或 Swift）、Android（Java 或 Kotlin）、React Native 或 Cordova。此集成不兼容任何其他框架！

支持内容

基本安装属性
支持 SkAdNetwork
苹果搜索广告归因
自定义应用内事件跟踪
收入跟踪
自定义用户 ID

不支持的功能

META 安装推荐人归属
深度链接
有限的数据共享支持

如果您需要其他框架的支持，或者需要Singular SDK提供的 "完整功能"，您必须独立于Rudderstack实现Singular SDK。请点击此处查看 SDK 选项和框架。

开始使用

从您的RudderStack 面板，添加源。然后，从目的地列表中选择Singular。
为目的地指定一个名称，然后单击 "继续"。

连接设置

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

API 密钥：在此输入 Singular 的"SDK 密钥"。这是必填字段。
密文：输入 Singular密文。这是必填字段，是与 RudderStack iOS 和 Android SDK 的设备模式集成所必需的。
获取您的 Singular"SDK 密钥"，可在 Singular 控制面板的"开发工具 > SDK 集成 > SDK 密钥 "下找到。

注意：对于 "云模式 "集成，您只需输入 API 密钥（SDK 密钥）值。
秘密 "留空。
会话事件名称：此设置仅适用于通过云模式发送事件。
使用设备模式发送事件：使用 Android 或 iOS 平台时，可以启用此设置通过设备模式发送事件。然后，按照 Singular 设备模式指南中的步骤将 Singular 添加到项目中。

通过设备模式发送事件时，RudderStack 还可以让你指定哪些事件应被丢弃或允许流过。更多信息，请参阅客户端事件过滤指南。

添加设备模式集成

在 RudderStack 中将 Singular 设置为目标后，根据你的集成平台，按照以下步骤将其添加到你的项目中。

要将 Singular 添加到 iOS 应用程序，请按照以下步骤操作：

在Podfile 中添加以下依赖项：

ruby

pod 'Singular-SDK', '11.0.4'
pod 'Rudder-Singular', '1.0.0'

添加依赖项后，执行pod install命令，在AppDelegate.m文件中添加以下导入：

Obj-C
```
//Objective-C
#import <rudder>
#import <ruddersingularfactory.h>
```

初始化RSClient：

Obj-C

//Objective-C
RSConfigBuilder *configBuilder = [[RSConfigBuilder alloc] init];
[configBuilder withDataPlaneUrl:<data_plane_url>];
[configBuilder withFactory:[RudderSingularFactory instance]];
RSClient *rudderClient = [RSClient getInstance:<write_key> config:[configBuilder build]];

Singular v11.0.4 及以上版本支持这种设备模式集成。

请按照以下步骤将 Singular 添加到您的 iOS 项目中：

在Podfile 中添加以下内容，安装RudderSingular（可通过CocoaPods 获取）：
```
pod 'RudderSingular', '~ 1.0.0'
```
通过pod install命令添加依赖关系后，根据首选平台在AppDelegate文件中添加导入：

斯威夫特
```
import RudderSingular
```
Obj-C
```
@import RudderSingular;
```

在 AppDelegate 文件中更新 didFinishLaunchingWithOptions 方法：

重要：

设置manualSkanConversionManagement = true将要求您手动更新自己的转换值。这将不允许 Singular 的 SKAN 模型代表您更新 CV 值。将此设置为 "false "可启用 "托管 "模式。
设置waitForTrackingAuthorizationWithTimeoutInterval只应在您的应用程序使用 iOS AppTrackingTransparency(ATT) Prompt时使用。如果显示 ATT，则应将此值设为 300。

迅捷

let config: RSConfig = RSConfig(writeKey: WRITE_KEY)
            .dataPlaneURL(DATA_PLANE_URL)

RSClient.sharedInstance().configure(with: config)
let rudderSingularConfig = RudderSingularConfig()
            .skAdNetworkEnabled(true)
            .manualSkanConversionManagement(true)
            .conversionValueUpdatedCallback({ value in
                print("Your SKAN handler \(value)")
            })
            .waitForTrackingAuthorizationWithTimeoutInterval(300)
RSClient.sharedInstance().addDestination(RudderSingularDestination(rudderSingularConfig: rudderSingularConfig))

Obj-C

RSConfig *config = [[RSConfig alloc] initWithWriteKey:WRITE_KEY];
[config dataPlaneURL:DATA_PLANE_URL];

[[RSClient sharedInstance] configureWith:config];
RudderSingularConfig *rudderSingularConfig = [[RudderSingularConfig alloc] init];
[rudderSingularConfig skAdNetworkEnabled:YES];
[rudderSingularConfig manualSkanConversionManagement:YES];
[rudderSingularConfig conversionValueUpdatedCallback:^(NSInteger value) {
    printf("Your SKAN handler %ld", value);
}];
[rudderSingularConfig waitForTrackingAuthorizationWithTimeoutInterval:300];
[[RSClient sharedInstance] addDestination:[[RudderSingularDestination alloc] initWithRudderSingularConfig:rudderSingularConfig]];

要在 Android 应用程序中添加 Singular，请按照以下步骤操作：

打开app/build.gradle（模块：app）文件，在依赖项部分添加以下内容：

groovy

implementation 'com.rudderstack.android.sdk:core:[1.0,2.0)'
implementation 'com.rudderstack.android.integration:singular:1.0.0'
implementation 'com.google.code.gson:gson:2.8.6'

在构建脚本中添加 Singular Maven 插件。为此，请将以下代码段添加到您的build. gradle根目录的Gradle 脚本部分：

groovy

buildscript {
    repositories {
        google()
        mavenCentral()
        maven {
          url 'https://maven.singular.net/'
        }
    }
    dependencies {
        classpath 'com.android.tools.build:gradle:7.1.2'
        classpath 'org.jetbrains.kotlin:kotlin-gradle-plugin:1.6.10'
    }
}
allprojects {
    repositories {
        google()
        mavenCentral()
        maven {
          url 'https://maven.singular.net/'
        }
    }
}

在AndroidManifest.xml 中添加以下权限（如果还没有）：

<uses-permission android:name="android.permission.INTERNET"></uses-permission>
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"></uses-permission>

最后，在应用程序类的onCreate()方法中初始化 RudderStack SDK：

// initialize Rudder SDK
val rudderClient =
    RudderClient.getInstance(
        this,
        WRITE_KEY,
        RudderConfig.Builder()
            .withDataPlaneUrl(DATA_PLANE_URL)
            .withFactory(SingularIntegrationFactory.FACTORY)
            .build()
    )

要在 React Native 应用程序中添加 Singular，请按照以下步骤操作：

运行以下命令，将RudderStack-Singular模块添加到应用程序中：

bash

npm install @rudderstack/rudder-integration-singular-react-native
// OR //
yarn add @rudderstack/rudder-integration-singular-react-native

打开项目级的android/build.gradle文件，添加以下代码段：

groovy
```
repositories {
  maven {
    url "https://maven.singular.net/"
  }
}
```

导入上述模块并将其添加到 SDK 初始化中：

typescript

import rudderClient from "@rudderstack/rudder-sdk-react-native"
import singular from "@rudderstack/rudder-integration-singular-react-native"
const config = {
	dataPlaneUrl: <data_plane_url>,
	trackAppLifecycleEvents: true,
	withFactories: [singular],
}
rudderClient.setup(<write_key>, config)

要在 Cordova 应用程序中添加 Singular，请按以下步骤操作：

导航至应用程序的根文件夹，然后运行以下命令：

bash
```
cordova plugin add rudder-integration-singular-cordova
```
在应用程序主页的onDeviceReady()函数中添加以下代码，以初始化 SDK：

javascript
```
RudderClient.initialize(<write_key>, {
  dataPlaneUrl: <data_plane_url>,
  factories: [RudderSingularFactory]
})
```
重要： 确保在调用`initialize`时使用`await`关键字。

识别

对于设备模式集成，Singular SDK 使用 RudderStack 的识别方法将用户 ID 映射到自定义用户 ID。RudderStack 使用 Singular 的setCustomUserIdAPI 将识别的用户 ID 转发给 Singular。

Android 和 iOS SDK 的识别调用示例如下：

[[RSClient getInstance] identify:@"1hKOmRA4el9Zt1WSfVJIVo4GRlm"];

RudderClient.getInstance()?.identify("1hKOmRA4el9Zt1WSfVJIVo4GRlm")

跟踪

跟踪调用可让您捕获任何用户操作以及与之相关的属性。每个用户操作都被视为一个事件。

跟踪自定义事件

自定义跟踪调用可让您跟踪应用程序中发生的自定义事件。RudderStack 会将这些调用发送到 Singular，在 Singular 中，它们会被处理为自定义安装后事件，并在相关报告中提供。

Android 和 iOS SDK 的自定义跟踪调用示例如下：

[[RSClient getInstance] track:@"Product Reviewed" properties:@{
        @"product_id" : @"345676543",
        @"review_id" : @"123454387"
    }];

RudderClient.getInstance()
    ?.track(
        "Product Reviewed",
        RudderProperty()
            .putValue("product_id", "345676543")
            .putValue("review_id", "123454387")
    )

跟踪收入

Singular 支持跟踪收入事件。只要发送了包含收入属性的事件（包括零值），它就会实现收入跟踪。您还可以选择将货币字段作为ISO 代码传递。

默认货币设置为美元。

收入跟踪调用示例如下：

[[RSClient getInstance] track:@"Order Completed" properties:@{
        @"revenue" : @1251,
        @"currency" : @"INR"
    }];

RudderClient.getInstance()
    ?.track(
        "Order Completed",
        RudderProperty().putValue("revenue", 1251).putValue("currency", "INR")
    )

屏幕

Screen方法允许您记录用户看到的移动屏幕以及任何相关的可选属性。此调用类似于网络应用程序的页面调用，但仅限于移动设备。

Android 和 iOS SDK 的屏幕调用示例如下：

[[RSClient sharedInstance] screen:@"Home" properties:@{
    @"category" : @"launcher"
}];

RudderClient.getInstance()
    ?.screen(
        "Home",
        RudderProperty().putValue("category", "launcher")
    )

在上述代码段中，RudderStack 会捕获与所查看屏幕相关的所有信息，以及关于屏幕的任何附加信息。

RudderStack 将屏幕事件作为自定义事件发送给 Singular。

重置

重置方法会重置当前用户的身份，并创建一个新的匿名会话。它应该在用户注销时调用。

RudderStack 调用 Singular 的unsetCustomUserId方法来重置用户身份。

Android 和 iOS SDK 的重置调用示例如下：

[[RSClient getInstance] reset];

RudderClient.getInstance()?.reset();

实现 SKAdNetwork (SKAN) 支持

在 iOS SDK 初始化之前添加以下代码，以便将 SKAdNetwork 集成控制权交给 Singular：

重要：

设置manualSkanConversionManagement = true将要求您手动更新自己的转换值。这将不允许 Singular 的 SKAN 模型代表您更新 CV 值。将此设置为 "false "可启用 "托管 "模式。
设置waitForTrackingAuthorizationWithTimeoutInterval只应在您的应用程序使用 iOS AppTrackingTransparency(ATT) Prompt时使用。如果显示的是 ATT，则应将此值设为 300。

Obj-C

[RudderSingularIntegration setSKANOptions:YES
        isManualSkanConversionManagementMode:NO
withWaitForTrackingAuthorizationWithTimeoutInterval:@300
        withConversionValueUpdatedHandler:^(NSInteger conversionValue){
    // Receive a callback whenever the Conversion Value is updated
    NSLog(@"SKAN handler %ld",conversionValue);
}];

Rudderstack - 奇异目的地（设备模式）

开始使用

连接设置

添加设备模式集成

识别

跟踪

跟踪自定义事件

跟踪收入

屏幕

重置

实现 SKAdNetwork (SKAN) 支持