React Native SDK - 基本集成

文档

开始之前:SDK 先决条件

按照集成 Singular SDK 中的步骤操作:规划和先决条件》中的步骤。

这些步骤是任何 Singular SDK 集成的先决条件。


安装 SDK

将 Singular React SDK 添加到项目中:

  1. 在项目根目录下打开终端。
  2. 使用以下命令将 SDK 包下载到项目中:

    bash
    npm install singular-react-native --save
  3. 如果你使用的是 React Native0.60+ 版本,Singular 软件包会自动链接到你的项目。

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

    bash
    react-native link singular-react-native
  4. 如果使用的是Expo:按照上述步骤安装 Singular SDK 后,将软件包添加到 app.json 或 app.config.js 的插件数组中:
    bash
    "expo": {
      "plugins": ["singular-react-native"]
    }
    然后使用 Expo 的本地代码定制指南重建应用程序。

设置先决条件

iOS 先决条件

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

bash
cd ios && pod install

Android 先决条件

project/build.gradle 文件的allprojects部分,将以下内容添加到应用程序的 Maven 资源库中:

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

添加所需的权限

AndroidManifest.xml文件的<manifest>标记下添加这些权限:

AndroidManifest.xml
<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" />
如果要集成Kids SDK,请排除 com.google.android.gms.permission.AD_ID 权限。

要支持三星 Galaxy Store 的安装引用程序,请添加以下内容:

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

如果已禁用 Singular SDK 的传递依赖关系,请app/build.gradle 中添加以下内容:

app/build.gradle
dependencies {
    ...
    implementation 'com.android.installreferrer:installreferrer:2.2'
    implementation 'com.google.android.gms:play-services-appset:16.0.0'
    ...
}

使用 Proguard 时的要求

在 React Native Android 中为 Singular SDK 配置 ProGuard

在 React Native Android 应用程序中集成 Singular Android SDK 时,必须添加特定的 ProGuard 规则,以确保 SDK 在发布版本中正常运行。ProGuard (或 R8,其现代替代品)在 React Native 发布版本中默认启用,用于优化和混淆代码。如果没有适当的 ProGuard 规则,Singular SDK 或其依赖项可能会被移除或混淆,从而导致运行时问题。

请按照以下步骤为 Singular SDK 配置 ProGuard:

  1. 找到 ProGuard 规则文件:在 React Native 项目中,导航到android/app/proguard-rules.pro 文件。该文件包含应用程序的自定义 ProGuard 规则。
  2. 添加 Singular SDK ProGuard 规则:将以下行添加到android/app/proguard-rules.pro ,以保留 Singular SDK 及其依赖关系:
proguard-rules.pro
# Preserve Singular SDK classes
-keep class com.singular.sdk.** { *; }

# Preserve Android Install Referrer library
-keep public class com.android.installreferrer.** { *; }

# Uncomment the following line if you are using the Singular 'revenue' function with Google Play Billing Library
#-keep public class com.android.billingclient.** { *; }

集成 SDK

:在实施Singular SDK时,切记要遵守业务所在地区颁布的各种隐私法,包括但不限于GDPR、CCPA和COPPA。如需了解更多信息,请参阅SDK 选择加入和选择退出实践

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

导入 Singular 库

App.jsApp.tsx 文件中,添加以下代码导入 Singular 类。

App.js or App.tsx
import {Singular, SingularConfig, Events, Attributes} from 'singular-react-native';

初始化 Singular SDK

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

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

    1. 在奇异配置对象中提供您的Facebook 应用程序 ID
      Singular config
      // To enable META Install Referrer
      
      config.withFacebookAppId('INSERT YOUR FACEBOOK APP ID HERE');
    在哪里可以找到应用程序的 Facebook 应用程序 ID?
  4. 然后,使用init 方法初始化 SDK,将 SingularConfig对象。

例如

App.js or App.tsx
const config = new SingularConfig('<SDK KEY>', '<SDK SECRET>');
  
// Optional settings:


// Set user ID if known at time of initialization

config.withCustomUserId('274e9db5c836093499df921be5'); 

// To enable META Install Referrer

config.withFacebookAppId('Insert your Facebook App ID here');

// Enables deep linking

config.withSingularLink(callBackFunction); 

// iOS - Enable SKAdNetwork

config.withSkAdNetworkEnabled(true);  

// iOS - Wait 5m for tracking authorization before sending any events

config.withWaitForTrackingAuthorizationWithTimeoutInterval(300);

// Initialize Singular SDK

 Singular.init(config);
Singular.init 方法
说明 初始化 Singular SDK
使用示例
Singular.init(config);

SingularConfig 选项

".with" 方法 说明
withCustomUserId(user_id) 向 Singular 发送用户 ID(了解更多)
withFacebookAppId(FACEBOOK_APP_ID)

注:在 Singular 配置对象中提供你的 Facebook 应用程序 ID,以启用 META 安装 Referrer Attribution。

withSingularLink(callBackFunction) 启用深度链接(了解更多)
withSessionTimeoutInSec(seconds) 修改会话超时(了解更多)