将 SDK 添加到您的项目

将 Singular React SDK 添加到项目中：

1. 在项目根目录下打开终端。

2. 使用以下命令将 SDK 包下载到项目中：

   npm install singular-react-native --save

3. 如果你使用的是 React Native0.60+ 版本，Singular 软件包会自动链接到你的项目。

   如果您使用的是 React Native0.59 或更旧的版本，请运行以下命令将 Singular 包中的本地桥接代码链接到您的项目：

   react-native link singular-react-native

设置先决条件

iOS 先决条件

在项目根目录下运行以下命令：

cd ios; pod install

Android 前提条件

在 build.gradle文件中，在应用程序的 Maven 资源库中添加以下内容：

allprojects {
  repositories {
    maven { url 'https://maven.singular.net/' }
  }
}

在应用程序的 AndroidManifest.xml文件中添加以下权限：

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

<!--  检索 Google Play Referrer 数据需要此权限。  -->
<uses-permission android:name="com.google.android.finsky.permission.BIND_GET_INSTALL_REFERRER_SERVICE" />

<!--  从 google 许可 API 获取数据需要此权限  -->
<uses-permission android:name="com.android.vending.CHECK_LICENSE" />

如果您的应用程序是针对 Android 12/API level 31 或更高版本构建的，请添加访问 Google Advertising ID 的权限：

<uses-permission android:name="com.google.android.gms.permission.AD_ID" />

如果您已禁用 Singular SDK 的传递依赖关系，请在应用程序的 build.gradle.

implementation 'com.android.installreferrer:installreferrer:2.2'
implementation 'com.google.android.gms:play-services-appset:16.0.0'

初始化 SDK

每次打开应用程序时，都应调用 SDK 初始化代码。它是所有Singular归因功能的前提，同时也会向Singular发送一个新的用户会话。会话用于计算用户留存率。

导入必填类

在App.js 文件中，添加以下代码导入 Singular 和 SingularConfigs 类。

import {Singular, SingularConfig, Events, Attributes} from 'singular-react-native';

配置和初始化 SDK

1. 在初始化 Singular SDK 之前，你必须创建一个 SingularConfig 对象。该对象包含 SDK 密钥和 SDK 秘密（登录 Singular 账户，进入 "开发工具 > SDK 集成 > SDK 密钥 "页面即可获取）。
2. 您还可以选择添加设置，以启用各种 SDK 功能。
3. 支持 META 安装推荐人归属

   启用"元安装推荐人 "属性所需的 SDK 配置：

   1. 在奇异配置对象中提供您的Facebook 应用程序 ID。
      

      // 启用 META 安装引荐来源网址
      config.withFacebookAppId("在此插入您的 FACEBOOK 应用程序 ID");

   在哪里可以找到应用程序的 Facebook 应用程序 ID？
4. 然后，使用init 方法初始化 SDK，传入 SingularConfig对象

例如

const config = new SingularConfig('<SDK KEY>', '<SDK SECRET>');
  
 // 可选设置：
 // 如果初始化时已知，则设置用户 ID
 config.withCustomUserId("274e9db5c836093499df921be5b7f32001d49c50"); 
  
 // 启用 META 安装推荐人
 config.withFacebookAppId("INSERT YOUR FACEBOOK APP ID HERE");
  
 // 实现深度链接
 config.withSingularLinks(callBackFunction); 
  
 Singular.init(config);

Singular.init(config);

向 Singular 发送用户 ID（可选）

您可以使用 Singular SDK 方法向 Singular 发送内部用户 ID。

• 用户 ID 可以是任何标识符，但不能暴露 PII（个人身份信息），例如，不能使用用户的电子邮件地址、用户名或电话号码。Singular 建议使用仅对第一方数据唯一的哈希值。
• 传递给Singular的用户ID值也应该是你在所有平台（Web/移动/PC/控制台/离线）上获取的相同的内部用户ID。
• Singular 将在用户级导出、ETL 和内部 BI 回传（如果配置）中包含用户 ID。用户 ID 是第一方数据，Singular 不会与其他方共享。
• 使用 Singular SDK 方法设置的用户 ID 值将一直存在，直到使用unsetCustomUserId 方法取消设置或卸载应用程序为止。关闭或重启应用程序不会取消设置用户 ID。

要设置用户 ID，请使用setCustomUserId 方法。要取消设置（例如，如果用户 "注销 "账户），请致电unsetCustomUserId 。

如果已经知道应用程序打开时的用户 ID，请在初始化 Singular SDK 之前调用setCustomUserId 。这样，Singular 就能从第一次会话中获得用户 ID。不过，在用户注册或登录之前，用户 ID 通常是不可用的。在这种情况下，请在注册流程完成后调用setCustomUserId 。

Singular.setCustomUserId("custom_user_id");

Singular.unsetCustomUserId();

Singular.setDeviceCustomUserId("CustomUserId");

处理 AppTrackingTransparency 同意

从 iOS 14.5 开始，在访问设备的 IDFA 进行追踪之前，必须先征得用户同意（使用 ATTrackingManager）。

如果想在征求用户同意前初始化 Singular SDK，可以在指定时间间隔内延迟 SDK 在没有 IDFA 的情况下触发事件，以等待用户同意。

为此，请使用waitForTrackingAuthorizationWithTimeoutInterval选项初始化 Singular SDK，如下例所示：

const config = new SingularConfig('<SDK KEY>', '<SDK SECRET>');
  
// 启用 SKAdNetwork
config.withSkAdNetworkEnabled(true);
  
// 在发送任何事件前等待 5m 的跟踪授权
config.withWaitForTrackingAuthorizationWithTimeoutInterval(300);
  
Singular.init(config);

跟踪事件（非收入）

Singular 可以收集应用内事件的相关数据，帮助分析营销活动的效果并衡量关键绩效指标。例如，您的企业可能希望收集有关用户登录、注册、教程完成或游戏应用中等级提升的数据。

Singular 支持各种 标准事件，这些常用事件通常由广告网络支持，用于报告和优化。另一个优点是，当你使用标准事件名称时，Singular 会自动识别并将其添加到事件列表中，而无需手动定义。我们建议尽可能使用标准事件。

发送到 Singular 的事件列表（附带属性）应由用户体验/营销/业务团队根据企业的营销关键绩效指标编制。业务团队可参考《如何跟踪应用内事件》指南：单一归因客户指南》。

您可以为跟踪的每个事件传递各种属性，请参阅推荐的每个事件的标准属性。

在代码中，使用event或eventWithArgs方法向 Singular 发送事件。

/* 发送标准活动登录信息 */
Singular.event(sngLogin);

/* 发送带有推荐属性的标准事件内容视图 */
Singular.eventWithArgs(sngContentView, { 
  sngAttrContentType: 'PrivacyController',
  sngAttrContentId: '130',
  sngAttrContent: 'GDPR Opt-Out Options'
});

跟踪收入

Singular 可以收集通过应用程序获得的收入数据，以帮助分析营销活动的绩效和投资回报率。Singular 将通过报告、日志导出和回传等方式向您提供这些数据。

在向 Singular 报告收入事件时，我们建议传递从 Android 或 iOS 的应用内购买（IAP）流程返回的购买对象。这样，Singular 就能获得交易的所有详细信息，从而丰富 Singular 报告的数据。此外，Singular 还能从谷歌获得交易收据，用于在打击应用内欺诈时验证交易。

在 React Native 中传递购买对象

// 添加奇异采购类导入
import {
   Singular,
   SingularConfig,
   SingularIOSPurchase,
   SingularAndroidPurchase,
  } from 'singular-react-native';
  
  let singularPurchase = null;
  
  if (Platform.OS === 'ios') {
   singularPurchase = new SingularIOSPurchase(
     product.revenue,
     product.currency,
     purchase.productId,
     purchase.transactionId,
     purchase.transactionReceipt,
   );
  } else if (Platform.OS === 'android'){
   singularPurchase = new SingularAndroidPurchase(
     product.revenue,
     product.currency,
     purchase.transactionReceipt,
     purchase.signatureAndroid,
   );
  }
  
  Singular.inAppPurchase('report iap', singularPurchase);

使用本地代码传递购买对象

iOS

// 向 Singular 报告交易详情
[Singular iapComplete:transaction];
  
// 以自定义名称向 Singular 报告交易详情
[Singular iapComplete:transaction withName:@"MyCustomRevenue"];

安卓

要利用 Android 的 IAP 功能，首先要在应用程序的 build.gradle文件中：

implementation 'com.singular.sdk:singular_sdk:9.+

Singular.revenue("USD", 5.50, purchase);

Singular.customRevenue("MyCustomRevenue", 
    "USD", 5.50, purchase);

不使用购买对象报告收入事件

虽然我们强烈建议按上述方式报告收入事件，但您也可以只通过传递货币和交易金额向 Singular 发送收入事件。请注意，Singular 不会获得购买收据，也无法验证交易。

Singular.revenue("USD", 5.50);

Singular.customRevenue("MyCustomRevenue", "USD", 5.50);

添加广告收入归属支持（高级）

混合事件跟踪（高级）

Singular 建议通过集成到应用程序中的 Singular SDK 发送所有事件和收入。不过，Singular 也可以从其他来源收集事件和收入。

任何非通过 Singular SDK 发送的事件都必须符合 Singular 的服务器到服务器事件文档要求，并提供匹配的设备标识符以正确归属事件。

混合事件跟踪指南

添加深度链接支持

深层链接是指向应用程序内部特定内容的链接。当用户在安装了应用程序的设备上点击深层链接时，应用程序就会打开并显示特定的产品或体验。

奇异跟踪链接可以包括深度链接和延迟深度链接（更多信息请参阅我们的 深度链接常见问题和奇异链接常见问题）。

下面的说明将告诉您如何

1. 访问导致您的应用程序被打开的跟踪链接、
2. 读取深度链接目的地，以及
3. 显示相应内容。

启用 Singular 链接

要在 iOS 和 Android 中启用 Singular Links，请参阅Singular Links Prerequisites。

处理奇异链接

Singular SDK 提供了一种处理机制，用于读取导致应用程序被打开的跟踪链接的详细信息。

要使用处理程序，请

1. 在创建 withSingularLinks创建 SingularConfig 对象。这将注册一个 Singular Links 处理程序。
2. 在处理程序中，调用或定义一个接收 SingularLinksParams 对象的回调函数，如下例所示。SingularLinksParams 对象包含以下字段：
   • deeplink- 在 _dl这是您需要解析的内容，以便向用户显示正确的产品或体验。
   • passthrough- 包含在 _p查询参数中包含的所有参数。
   • isDeferred- 如果是延迟的深度链接，则为 true。
   • urlParameters- 奇异跟踪链接的所有查询字符串参数。
     • 您必须将 _forward_params=1 键/值对附加到奇异跟踪链接，以便 SDK 提供所有查询字符串参数。

const config = new SingularConfig('<SDK KEY>', '<SDK SECRET>');
  config.withSingularLink(singularLinksParams => {
      const deeplink = singularLinksParams.deeplink;
      const passthrough = singularLinksParams.passthrough;
      const isDeferred = singularLinksParams.isDeferred;
      const urlParameters = singularLinksParams.urlParameters;
      
      // 在此处添加代码以处理深层链接
  });
  //...
  Singular.init(config);

设置先决条件

iOS 先决条件

在项目的 AppDelegate.m中添加以下内容：

// AppDelegate.m 顶部
  #import <Singular-React-Native/SingularBridge.h>
  
  - (BOOL)application:(UIApplication *)application 
    didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
      // 在 didFinishLaunchingWithOptions 内添加
      [SingularBridge startSessionWithLaunchOptions:launchOptions];
    return YES;
  }
  
  // 将此方法添加到应用程序委托中
  - (BOOL)application:(UIApplication *)application 
    continueUserActivity:(NSUserActivity *)userActivity 
      restorationHandler:(void (^)(NSArray<id> * _Nullable))restorationHandler{
        [SingularBridge startSessionWithUserActivity:userActivity];
        return YES;
  }

Android 前提条件

在项目的 MainActivity.java中，添加以下内容：

// 作为导入的一部分添加在类的顶部
import android.content.Intent;
import net.singular.react_native.SingularBridgeModule;
  
// 添加到 MainActivity 类
  @Override
  public void onNewIntent(Intent intent) {
    if(intent.getData() != null) {
      setIntent(intent);
      super.onNewIntent(intent);
      SingularBridgeModule.onNewIntent(intent);
    }
  }

简介：SKAdNetwork 和 SKAN

SKAdNetwork是苹果公司在不损害最终用户隐私的前提下，为移动安装提供属性的新框架。Singular 的新版 iOS SDK 可帮助您以最小的工程投入无缝实施 SKAdNetwork。该SKAdNetwork实施基于SKAN--Singular为顺利实施SKAdNetwork而开发的标准。

有关 Singular SKAdNetwork 实施的完整指南，请参阅iOS SDK SKAdNetwork 实施指南。

启用 SKAdNetwork 跟踪

要为应用程序启用 SKAdNetwork 跟踪功能，请在初始化 Singular 之前打开 skAdNetworkEnabled 配置选项：

const config = new SingularConfig('<SDK KEY>', '<SDK SECRET>');

// 启用 SKAdNetwork
config.withSkAdNetworkEnabled(true);

// 在转换值更新时注册回调函数
config.conversionValueUpdatedHandler(value => {
	console.log(`Updated conversion value: ${value}`);
  });

Singular.init(config);

处理转换值更新

托管模式

默认情况下，SKAdNetwork 实现直接从 Singular 服务器端管理转换值。

这样可以最大限度地提高灵活性，因为您可以通过 Singular 平台设置和更改转换值，而无需修改客户端代码。

这种服务器端管理模式还有助于您处理SKAdNetwork 定时器。SKAdNetwork 允许您在注册 SKAdNetwork 后 24 小时内更新转换值。任何更新转换值的调用都会将计时器延长 24 小时。因此，在选择转换事件时，您必须确保事件在该更新窗口内发生。在托管模式下，您可以随时更改转换事件配置，而无需发布应用程序的新版本。

手动模式

如果您想在应用程序代码中自行更新转换值，请在初始化 SDK 时调用withManualSkanConversionManagement：

const config = new SingularConfig('<SDK KEY>', '<SDK SECRET>');
// 启用 SKAdNetwork
config.withSkAdNetworkEnabled(true);

// 启用手动转换值更新
config.withManualSkanConversionManagement();

Singular.init(config);

然后，在应用程序生命周期中需要更新转换值的地方使用skanUpdateConversionValue方法：

// 发生了报名活动
Singular.event("SignUp");

// 将转换值更新为 7
Singular.skanUpdateConversionValue(7);

检索转换值

要获取当前转换值，请使用skanGetConversionValue方法。该方法在托管模式和手动模式下均有效。

const conversionValue = Singular.skanGetConversionValue();

创建短链接

使用短链接可将冗长、充满参数的 Singular 链接转换为更短、更安全的链接，方便共享。

通常情况下，您需要动态创建短链接，以便应用程序的用户可以与朋友分享，邀请他们使用应用程序。

要创建短链接，您需要

• 指向应用程序下载的奇异链接（请参阅奇异链接常见问题）。
• 要动态添加到链接中的任何参数（选项列表请参阅跟踪链接参数）。
• 推荐用户的姓名和 ID，如果您希望跟踪新应用的安装情况，并追溯到共享链接的用户。

使用createReferrerShortLink方法创建短链接，如下例所示。

Singular.createReferrerShortLink (
    "https://sample.sng.link/B4tbm/v8fp?_dl=https%3A%2F%2Fabc.com",
    "John Doe", // 推荐人姓名
    "aq239897", // 推荐人 ID
    {"channel": "sms"}, // 要添加到链接中的任何参数
    (shortLinkURL,error) => {
      /* 如果 shortLinkURL 不为空，则在此处添加共享逻辑。如果出现错误，则根据错误原因添加重试/尝试/修改传递给函数的参数的逻辑。 */
    }
)

跟踪卸载

要让 Singular 跟踪应用程序的卸载情况：

1. 首先，在Singular平台中配置应用程序，详见设置卸载跟踪 [Android][iOS]。
2. 使用首选方法在 React Native 中检索APNS/FCM令牌。
3. 调用setUninstallToken方法，像下面的示例一样传递 APNS/FCM 令牌。请确保根据设备平台传递正确的令牌。

if (Platform.OS === 'ios') {
  Singular.setUninstallToken(apnsToken);
} else if (Platform.OS === 'android'){
  Singular.setUninstallToken(fcmToken);
}

修改会话超时

Singular SDK 会自动管理用户会话，因此你不需要添加任何代码来处理会话。不过，您可以根据需要修改会话超时值。

默认情况下，如果应用程序在后台运行 60 秒或更长时间后才返回前台，SDK 就会注册一个新会话。

要更改超时值，请在创建 SingularConfig 对象时使用.withSessionTimeoutInSec。例如

const config = new SingularConfig('<SDK KEY>', '<SDK SECRET>')
    .withSessionTimeoutInSec(120); // 将超时设置为 120 秒
Singular.init(config);

遵守数据隐私法

Singular提供隐私保护功能，帮助您与任何可能遵守消费者隐私法（如GDPR和CCPA（加州消费者隐私法））的合作伙伴合作。 这些合作伙伴希望在最终用户同意共享其私人信息时得到通知。

限制数据共享

如果你已经实施了一种征求用户同意共享其信息的方法，请使用limitDataSharing方法通知 Singular 用户的选择：

• 使用limitDataSharing:NO表示用户同意（选择加入）共享其信息。
• 如果用户不同意，则使用 limitDataSharing:YES。

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

// 用户已选择共享数据
Singular.limitDataSharing(false);

遵守 GDPR 的其他方法

Singular SDK 提供了多种方法，帮助您遵守 GDPR 政策，并让 Singular 了解用户是否同意追踪。

Singular.trackingOptIn();

Singular.stopAllTracking();

Singular.resumeAllTracking();

Singular.isAllTrackingStopped();