观看此视频,详细了解集成流程。 我们建议 您同时参考视频和下方的文字指南。
先决条件
在安装 Singular Flutter SDK 之前,请完成以下必备步骤,以确保集成过程顺利进行。
必备条件:
- 完成规划步骤:请遵循《集成 Singular SDK:规划与先决条件》中的指南。这些步骤是任何 Singular SDK 集成的必备条件。
- Flutter 版本:请确认您已拥有一个安装了 Flutter SDK 且可正常运行的 Flutter 应用程序。
- SDK 凭据:请在 Singular 平台的“开发者工具 > SDK 集成 > SDK 密钥”中获取您的 SDK 密钥和密钥密文。
安装
安装 SDK 包
使用 pubspec.yaml 依赖管理器将 Singular Flutter SDK 添加到您的项目中。 该 SDK 为 iOS 和 Android 原生 Singular SDK 提供了 Dart 绑定。 iOS 和 Android 原生 Singular SDK。
添加 SDK 依赖项
-
更新 pubspec.yaml:在项目的
pubspec.yaml文件中 添加 Singular Flutter SDK 依赖项:dependencies: flutter: sdk: flutter singular_flutter_sdk: ^1.8.0 -
安装依赖项:在终端中导航至项目目录,
并运行:
flutter packages get
平台配置
iOS 配置
完成 iOS 特定的设置,以启用 AdServices 框架对 iOS 归因跟踪的支持。
添加 AdServices 框架
Apple Search Ads 归因 以及 iOS 14.3 及以上版本的 SKAdNetwork 集成需要 AdServices 框架。
-
导航至 iOS 项目:打开 Flutter 项目的
iOS 目录,找到 Xcode 工作区。
-
导航至 Flutter 项目的
ios文件夹。 -
在 Xcode 中打开
Runner.xcworkspace(若使用 CocoaPods,请使用.xcworkspace;否则 请使用.xcodeproj)。
-
导航至 Flutter 项目的
-
添加 AdServices 框架:在 Xcode 项目设置中配置该框架。
- 在 Xcode 中,选择您的项目目标(例如“Runner”)。
- 转到“通用”选项卡。
- 滚动至 “框架、库和嵌入式内容” 部分。
- 点击“+”按钮。
-
搜索
AdServices.framework并添加它。 - 将框架状态设置为“可选”(确保 与旧版 iOS 兼容)。
为何选择“可选”?将 AdServices 设为可选可确保 您的应用与未包含 此框架的 iOS 版本(iOS 14.2 及更早版本)保持兼容。
Android 配置
配置您的 Android 构建文件,以添加必要的权限和依赖项, 确保 SDK 功能正常运行。
添加所需权限
在 `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" />
重要提示:若您正在集成
儿童版 SDK,请排除
com.google.android.gms.permission.AD_ID 权限。
此权限在标准应用中用于收集 GAID,
但针对 13 岁以下儿童的应用必须省略。
Samsung Galaxy Store 支持
若要启用来自 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 的功能。
为何重要:ProGuard 在 Flutter Android 发布构建中默认启用。 若未设置正确的保留规则, SDK 在生产环境中可能无法正常运行。
-
查找 ProGuard 文件:在您的 Flutter 项目中导航至
android/app/proguard-rules.pro。 -
添加保留规则:在文件末尾添加以下规则以保留
SDK 类:
# 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 集成
隐私合规:在 实施 Singular SDK 时,请遵守您运营地区的隐私法律,包括 GDPR、CCPA、COPPA 等。 有关指导,请参阅 SDK 选择加入和选择退出实践。
每次应用启动时,请初始化 Singular SDK。SDK 初始化 对于所有 Singular 归因功能至关重要,并会创建一个 新的会话用于计算用户留存指标。
导入 SDK 类
请在主应用程序文件(通常为main.dart )的顶部
导入 Singular SDK 类。
import 'package:singular_flutter_sdk/singular.dart';
import 'package:singular_flutter_sdk/singular_config.dart';
初始化 SDK
使用您的 SDK 凭据创建一个SingularConfig 对象,
配置可选功能,并使用
start() 方法初始化 SDK。
基本初始化
- 获取凭据:登录您的 Singular账户 并导航至 开发者工具 > SDK 集成 > SDK密钥 以查找您的 SDK 密钥和密钥密文。
-
创建配置:使用凭据实例化
SingularConfig对象。 - 添加配置:可选地使用归因设置器配置 SDK 行为 (参见 配置参考)。
-
初始化 SDK:调用
Singular.start()以启动 SDK。
初始化示例
在应用的入口点初始化 SDK,通常位于
主 StatefulWidget 的initState() 方法中。
import 'package:flutter/material.dart';
import 'package:singular_flutter_sdk/singular.dart';
import 'package:singular_flutter_sdk/singular_config.dart';
void main() {
runApp(MyApp());
}
class MyApp extends StatefulWidget {
@override
_MyAppState createState() => _MyAppState();
}
class _MyAppState extends State<MyApp> {
@override
void initState() {
super.initState();
// Create configuration with credentials
SingularConfig config = SingularConfig(
'YOUR_SDK_KEY',
'YOUR_SDK_SECRET'
);
// Enable debug logging
config.enableLogging = true;
config.logLevel = 4;
// Set session timeout (in seconds)
config.sessionTimeout = 60.0;
// Initialize SDK
Singular.start(config);
}
@override
Widget build(BuildContext context) {
return MaterialApp(
title: 'Flutter Demo',
home: MyHomePage(),
);
}
}
高级配置示例
在初始化过程中配置多个 SDK 功能,方法是在调用
start() 之前,对SingularConfig 对象设置额外的
归因。
import 'package:flutter/material.dart';
import 'package:singular_flutter_sdk/singular.dart';
import 'package:singular_flutter_sdk/singular_config.dart';
import 'package:singular_flutter_sdk/singular_link_params.dart';
import 'package:singular_flutter_sdk/singular_global_property.dart';
void main() {
runApp(MyApp());
}
class MyApp extends StatefulWidget {
@override
_MyAppState createState() => _MyAppState();
}
class _MyAppState extends State<MyApp> {
@override
void initState() {
super.initState();
initializeSingularSDK();
}
void initializeSingularSDK() {
// Create configuration with credentials
SingularConfig config = SingularConfig(
'YOUR_SDK_KEY',
'YOUR_SDK_SECRET'
);
// User identification
config.customUserId = 'user_123456';
// Privacy settings
config.limitDataSharing = false;
// Deep linking handler
config.singularLinksHandler = (SingularLinkParams params) {
print('Deep link received: ${params.deeplink}');
print('Passthrough params: ${params.passthrough}');
print('Is deferred: ${params.isDeferred}');
// Handle navigation based on deep link
};
// Short link timeout
config.shortLinkResolveTimeOut = 10.0;
// Facebook integration
config.facebookAppId = 'YOUR_FACEBOOK_APP_ID';
// SKAdNetwork settings (iOS)
config.skAdNetworkEnabled = true;
config.manualSkanConversionManagement = false;
config.waitForTrackingAuthorizationWithTimeoutInterval = 30;
// Conversion value callbacks (iOS)
config.conversionValueUpdatedCallback = (int conversionValue) {
print('Conversion value updated: $conversionValue');
};
config.conversionValuesUpdatedCallback = (int cv, int coarse, bool lock) {
print('Fine: $cv, Coarse: $coarse, Locked: $lock');
};
// Global properties
config.globalProperties = [
SingularGlobalProperty('app_version', '2.5.0', true),
SingularGlobalProperty('user_tier', 'premium', false)
];
// Debugging
config.enableLogging = true;
config.logLevel = 4;
// Session timeout
config.sessionTimeout = 60.0;
// Initialize SDK
Singular.start(config);
}
@override
Widget build(BuildContext context) {
return MaterialApp(
title: 'Flutter Demo',
home: MyHomePage(),
);
}
}
配置参考:有关 可用配置选项的完整列表,请参阅 Flutter SDK 配置参考。
重要提示:请勿使用 Singular 报告 API 密钥。仅使用 SDK 集成 页面中提供的 SDK 专用凭据。使用错误的凭据将导致数据无法发送至 Singular。
高级配置
Google Ads iOS 集成转化测量必备配置
如果您的应用运行针对 iOS 14.5+ 用户的 Google Ads 广告系列,则需要 执行额外的 SDK 配置步骤以支持 iOS 集成转化 测量 (ICM)。这包括:
- 集成 Google 的设备端测量 (ODM) SDK
- 更新至 Singular iOS SDK v12.8.1 及以上版本(或 Unity 版 v5.5.0 及以上、Flutter/Cordova 版 v1.8.0 及以上、React Native 版 v3.9.0 及以上)
-
添加
-ObjC链接器标志,并在SingularConfig中启用enableOdmWithTimeoutInterval
注意:启用enableOdmWithTimeoutInterval 会延迟 SDK
的初始化,并可能推迟深度链接回调。请在初始 SDK 实现阶段
完成此配置,以避免返工。