先决条件

在安装 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"]
    }
  }

  然后使用世博会的定制原生代码指南重建应用程序。

平台配置

iOS 配置

完成 iOS 特定设置，启用 CocoaPods 依赖项，确保 SDK 功能正常。

安装 CocoaPods 依赖项

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

cd ios && pod install

安卓配置

配置 Android 构建文件，添加 Singular Maven 资源库、所需权限和依赖项。

添加 Maven 资源库

在项目的build.gradle 文件中添加 Singular Maven 仓库，以启用 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" />

三星 Galaxy 商店支持

要启用来自 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 类

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

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

// Import Native API and EventEmitter
import NativeSingular from 'singular-react-native/jsNativeSingular';
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/jsNativeSingular';

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/jsNativeSingular';
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
  );
}