开始之前:SDK 先决条件
按照集成 Singular SDK 中的步骤操作:规划和先决条件》中的步骤。
这些步骤是任何 Singular SDK 集成的先决条件。
安装 SDK
将 Singular React SDK 添加到项目中:
- 在项目根目录下打开终端。
-
使用以下命令将 SDK 包下载到项目中:
npm install singular-react-native --save
- 如果你使用的是 React Native0.60+ 版本,Singular 软件包会自动链接到你的项目。
-
如果您使用的是 React Native0.59 或更旧的版本,请运行以下命令将 Singular 包中的原生桥接代码链接到您的项目:
react-native link singular-react-native
- 如果使用的是Expo:如上所述安装 Singular SDK 后,将软件包添加到app.json 或app.config.js 的插件数组中:
"expo": { "plugins": ["singular-react-native"] }
设置先决条件
iOS 先决条件
在项目根目录下运行以下命令:
cd ios && pod install
Android 先决条件
在project/build.gradle 文件的allprojects部分,将以下内容添加到应用程序的 Maven 资源库中:
allprojects {
repositories {
maven { url 'https://maven.singular.net/' }
}
}
添加所需的 Android 权限和依赖关系
在AndroidManifest.xml文件的<manifest>标记下添加这些权限:
<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 Store 的安装推荐器,请添加以下内容:
<queries>
<package android:name="com.sec.android.app.samsungapps" />
</queries>
如果已禁用 Singular SDK 的传递依赖关系,请在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:
- 找到 ProGuard 规则文件:在 React Native 项目中,导航到android/app/proguard-rules.pro 文件。该文件包含应用程序的自定义 ProGuard 规则。
- 添加 Singular SDK ProGuard 规则:将以下行添加到android/app/proguard-rules.pro ,以保留 Singular SDK 及其依赖关系:
# 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 类。
import { Singular, SingularConfig, Events, Attributes } from 'singular-react-native';
初始化 Singular SDK
- 创建SingularConfig 对象。该对象包含 SDK 密钥和 SDK Secret(登录 Singular 账户并导航至"开发人员工具 > SDK 集成 > SDK 密钥"以获取密钥和 Secret)。
-
可选择添加多个配置方法来设置或启用各种 SDK 功能。
- 然后,使用init 方法初始化 SDK,将 SingularConfig对象。
例如
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
);
}