先决条件

在安装 Singular React Native SDK 之前，请完成以下先决条件步骤，以确保集成过程顺利。

安装

安装 SDK 包

使用 npm 将 Singular React Native SDK 添加到您的项目中。该 SDK 为 iOS 和 Android 原生 Singular SDK 提供了 JavaScript 绑定。

通过 NPM 安装

1. 打开终端：导航至项目的根目录。
2. 安装包：运行以下命令将 SDK 添加到您的项目中：
   bash

   npm install singular-react-native --save

链接原生模块

SDK 的链接方式取决于您的 React Native 版本以及 是否使用 Expo。

• React Native 0.60+：SDK 会自动链接。 无需额外操作。
• React Native 0.59 或更早版本：手动链接原生 桥接代码：
  bash

  react-native link singular-react-native

• Expo 项目：安装 SDK 后，将其 添加到插件配置中：
  app.json

  {
    "expo": {
      "plugins": ["singular-react-native"]
    }
  }

  然后按照 Expo 的 自定义原生代码指南重建应用。

平台配置

iOS 配置

完成 iOS 专属设置以启用 CocoaPods 依赖项，并确保 SDK 功能正常。

安装 CocoaPods 依赖项

在项目根目录下运行以下命令以安装 所需的 iOS 依赖项：

cd ios && pod install

Android 配置

配置您的 Android 构建文件，以添加 Singular Maven 仓库、 所需权限及依赖项。

添加 Maven 仓库

将 Singular Maven 仓库添加到项目的 build.gradle 文件中，以启用 SDK 依赖项解析。

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

添加所需权限

在AndroidManifest.xml 文件的 <manifest> 标签下添加以下权限，以启用核心 SDK 功能。

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="BIND_GET_INSTALL_REFERRER_SERVICE" />
<uses-permission android:name="com.android.vending.CHECK_LICENSE" />
<uses-permission android:name="com.google.android.gms.permission.AD_ID" />

Samsung Galaxy Store 支持

若要启用来自 Samsung Galaxy Store 的安装来源追踪，请在您的 AndroidManifest.xml 中添加以下内容：

<queries>
   <package android:name="com.sec.android.app.samsungapps" />
</queries>

传递性依赖项

如果您已在 Gradle 配置中禁用了 Singular SDK 的 传递性依赖，请手动添加以下必需依赖项：

dependencies {
    // Required for install referrer tracking
    implementation("com.android.installreferrer:installreferrer:2.2")

    // Required for App Set ID
    implementation("com.google.android.gms:play-services-appset:16.0.0")
}

ProGuard 配置

在构建发布版 APK 时，ProGuard（或 R8）可能会剥离或混淆 SDK 类。请添加以下保留规则以保持 Singular 的功能。

1. 查找 ProGuard 文件：导航至 项目中的android/app/proguard-rules.pro 。
2. 添加保留规则：将以下规则追加到 该文件中：
   proguard-rules.pro

   # Preserve Singular SDK classes
   -keep class com.singular.sdk.** { *; }
   
   # Preserve Android Install Referrer library
   -keep public class com.android.installreferrer.** { *; }
   
   # Uncomment if using Singular revenue tracking with Google Play Billing Library
   #-keep public class com.android.billingclient.** { *; }

SDK 集成

导入 SDK 类

在主应用程序文件的顶部导入 Singular SDK 类 （通常为App.tsx 或App.js ）。

// Direct TurboModule API initialization (React Native 0.76+)

// Import Native API and EventEmitter
import NativeSingular from 'singular-react-native/js/NativeSingular';
import { NativeEventEmitter } from 'react-native';

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

初始化 SDK

基本初始化

1. 获取凭据：登录您的 Singular账户 并导航至 开发者工具 > SDK 集成 > SDK密钥 以查找您的 SDK 密钥和密钥密文。
2. 创建配置：使用您的凭据实例化 SingularConfig 对象，或为 TurboModule API 创建普通对象。
3. 添加配置：可选地串联配置 方法（旧版）或在配置对象中 直接添加归因 （TurboModule）。
4. 初始化 SDK：调用Singular.init() 或NativeSingular.init() 来启动 SDK。

初始化示例

在应用的入口点初始化 SDK，通常位于 useEffect 钩子中，以确保其在应用启动时仅运行一次。

// TurboModule direct API (React Native 0.76+ New Architecture)
import React, { useEffect } from 'react';
import NativeSingular from 'singular-react-native/js/NativeSingular';

export default function App() {
  useEffect(() => {
    const config: SingularConfig = {
      apikey: 'YOUR_SDK_KEY',
      secret: 'YOUR_SDK_SECRET',
      enableLogging: true,
      logLevel: 3,
    };

    NativeSingular.init(config);

  }, []);
  
  return (
    // Your app components
  );
}

import React, { useEffect } from 'react';
import Singular, { SingularConfig } from 'singular-react-native';

export default function App() {
  useEffect(() => {
    const config = new SingularConfig('YOUR_SDK_KEY', 'YOUR_SDK_SECRET')
      .withLoggingEnabled()
      .withLogLevel(3);
    
    Singular.init(config);
  }, []);
  
  return (
    // Your app components
  );
}
      

高级配置示例

在调用init() 之前，通过链式调用配置 方法，在初始化时配置多个 SDK 功能。

// TurboModule direct API (React Native 0.76+ New Architecture)
import React, { useEffect } from 'react';
import NativeSingular from 'singular-react-native/js/NativeSingular';
import { NativeEventEmitter } from 'react-native';

export default function App() {
  useEffect(() => {
    const config: SingularConfig = {
      apikey: 'YOUR_SDK_KEY',
      secret: 'YOUR_SDK_SECRET',
      customUserId: 'user_123456',
      limitDataSharing: false,
      waitForTrackingAuthorizationWithTimeoutInterval: 300
    };

    NativeSingular.init(config);

    // Register event listener
    const emitter = new NativeEventEmitter(NativeSingular);
    emitter.addListener('SingularLinkHandler', (params) => {
      console.log('Singular: Deep link:', params.deeplink);
      console.log('Singular: Passthrough:', params.passthrough);
      console.log('Singular: Is deferred:', params.isDeferred);
      console.log('Singular: urlParameters:', params.urlParameters);
    });

  }, []);
  
  return (
    // Your app components
  );
}

import React, { useEffect } from 'react';
import { Singular, SingularConfig } from 'singular-react-native';

export default function App() {
  useEffect(() => {
    const config = new SingularConfig(
      'YOUR_SDK_KEY',
      'YOUR_SDK_SECRET'
    )
      // User identification
      .withCustomUserId('user_123456')

      // Privacy settings
      .withLimitDataSharing(false)

      // Deep linking
      .withSingularLink((params: SingularLinkParams) => {
        console.log('Singular: Deep link:', params.deeplink);
        console.log('Singular: Passthrough:', params.passthrough);
        console.log('Singular: Is deferred:', params.isDeferred);
        console.log('Singular: urlParameters:', params.urlParameters);
      })

      // iOS-specific
      .withWaitForTrackingAuthorizationWithTimeoutInterval(300)

      // Debugging
      .withLoggingEnabled()
      .withLogLevel(3);

    Singular.init(config);
  }, []);

  return (
    // Your app components
  );
}

高级配置

Google Ads iOS 集成转化测量所需配置

如果您的应用运行针对 iOS 14.5 及以上版本用户的 Google Ads 广告系列，则需要执行额外的 SDK 配置步骤以支持 iOS 集成转化 测量 (ICM)。这包括：

• 集成 Google 的设备端测量 (ODM) SDK
• 更新至 Singular iOS SDK v12.8.1 及以上版本（或 Unity 版 v5.5.0 及以上、Flutter/Cordova 版 v1.8.0 及以上、React Native 版 v3.9.0 及以上）
• 添加-ObjC 链接器标志，并在SingularConfig中启用 enableOdmWithTimeoutInterval

注意：启用enableOdmWithTimeoutInterval 会延迟 SDK 的初始化，并可能推迟深度链接回调。请在初始 SDK 实现阶段完成此配置， 以避免返工。

参阅完整的 iOS ICM 技术要求