React Native SDK - 基本集成

文档

开始之前:SDK 先决条件

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

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


安装 SDK

将 Singular React SDK 添加到项目中:

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

    bash
    npm install singular-react-native --save
    • 如果你使用的是 React Native0.60+ 版本,Singular 软件包会自动链接到你的项目。
    • 如果您使用的是 React Native0.59 或更旧的版本,请运行以下命令将 Singular 包中的原生桥接代码链接到您的项目:

      bash
      react-native link singular-react-native
    • 如果使用的是Expo:如上所述安装 Singular SDK 后,将软件包添加到app.jsonapp.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/' }
  }
}

添加所需的 Android 权限和依赖关系

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.tsx 文件中,添加以下代码导入 Singular 类。

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

初始化 Singular SDK

  1. 创建SingularConfig 对象。该对象包含 SDK 密钥和 SDK Secret(登录 Singular 账户并导航至"开发人员工具 > SDK 集成 > SDK 密钥"以获取密钥和 Secret)。
  2. 可选择添加多个配置方法来设置或启用各种 SDK 功能。

  3. 然后,使用init 方法初始化 SDK,将 SingularConfig对象。

例如

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

export default function App() {
  useEffect(() => {
    // Create Singular configuration
    const config = new SingularConfig('SDK KEY', 'SDK SECRET')
      .withCustomUserId('user_123456') // Set a custom user ID for tracking
      .withLimitDataSharing(false) // Allow data sharing (set to true for compliance if needed)
      .withFacebookAppId('123456789012345') // Optional: For Facebook integration
      .withLogLevel(3) // Enable verbose logging for debugging
      .withLoggingEnabled(); // Enable SDK logs

    // Define SingularLink callback for deep linking
    const handleSingularLink = (params: any) => {
      console.log('SingularLink params:', params);
      // Example: Navigate to a specific screen based on params.deeplink
    };

    // Initialize Singular SDK
    Singular.init(config, handleSingularLink);

  }, []); // Empty dependency array ensures this runs once on app start

  return (
    // Your app's UI components
  );
}