React Native SDK - 基本集成

关注
Avatar
Kesava Peteti
Updated
文档

开始之前：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.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/' }
  }
}

添加所需的 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
  );
}