观看视频,详细了解集成过程。我们建议您同时使用视频和下面的书面指南。
开始之前:SDK 先决条件
Singular SDK 可作为 Flutter 的插件使用。以下说明将向您介绍如何将 Singular 集成到 Flutter 应用程序中。
- 本文假定您有一个功能正常的 Flutter 应用程序。
- 要初始化 SDK,您需要 Singular SDK Key 和 SDK Secret。您可以在 Singular 平台的"开发工具 > SDK 集成 > SDK 密钥"中获取它们。
集成 SDK
要在 Flutter 应用程序中添加 Singular 插件,请在pubspec.yaml文件中添加以下几行:
dependencies:
singular_flutter_sdk: ^1.6.1
然后在终端中导航到您的项目并运行以下程序:
flutter packages get
针对 Android 的其他步骤
添加依赖关系
对于 Android 应用程序,您需要在app/build.gradle 的依赖关系列表中添加 Singular 库,如下所示:
dependencies {
implementation fileTree(dir: 'libs', include: ['*.jar'])
implementation 'com.android.support:appcompat-v7:28.0.0'
//...
}
Singular SDK 需要 Google 移动广告 API,它是 Google Play 服务 API 17.0.0+ 的一部分。如果您已经在应用程序中集成了 Google Play 服务,则已满足要求。如果尚未集成,可以在应用程序的build.gradle 中加入以下依赖项,单独集成 Google Mobile Ads:
implementation 'com.google.android.gms:play-services-ads-identifier:18.0.1'
如果您已禁用 Singular SDK 的传递依赖关系,请在应用程序的build.gradle 中添加以下内容。
implementation 'com.android.installreferrer:installreferrer:2.2'
implementation 'com.google.android.gms:play-services-appset:16.0.2'
此外,如果您的应用程序通过三星 Galaxy Store 发布,请添加以下内容以支持三星 Galaxy Store 的安装引用程序:
implementation 'store.galaxy.samsung.installreferrer:samsung_galaxystore_install_referrer:4.0.0'
注: 如果在构建时出现DuplicateClasses(重复类 )错误,则可能已经有了 Google play-services,可以注释掉该依赖关系。
添加权限
在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" />
此外,如果您的应用程序是通过 Samsung Galaxy Store 发布的,并且针对 Android 11 或更高版本,请添加以下内容以支持 Samsung Galaxy Store 的安装引用程序:
<queries>
<package android:name="com.sec.android.app.samsungapps" />
</queries>
如果您的应用程序构建针对 Android 12/API level 31 或更高版本,请添加访问 Google Advertising ID 的权限:
<uses-permission android:name="com.google.android.gms.permission.AD_ID" />
注意:如果您集成了儿童 SDK,请勿添加此权限。
iOS 的其他步骤
要使用 Singular 插件,必须添加 AdServices 框架。
初始化 Singular SDK
每次打开应用程序时,都应调用 Singular SDK 初始化代码。这是所有 Singular 归因功能的前提条件,它还会向 Singular 发送一个新的用户会话(会话用于计算用户留存)。
初始化代码位于应用程序的主窗口部件(即 main.dart)中,也就是应用程序打开时加载的第一个窗口部件。该部件必须是有状态的,代码必须添加到部件的initState()方法中。
- 首先,你必须创建一个 SingularConfig 对象。该对象包含你的 Singular SDK 密钥和秘密。
- 您还可以选择添加设置,以启用各种 SDK 功能。请参阅完整的选项列表。
- META 安装推荐人归属支持
启用"元安装推荐人 "属性所需的 SDK 配置:
- 在奇异配置对象中提供您的Facebook 应用程序 ID。
// To enable META Install Referrer config.facebookAppId = "INSERT YOUR FACEBOOK APP ID HERE";
- 在奇异配置对象中提供您的Facebook 应用程序 ID。
示例:
import 'package:singular_flutter_sdk/singular.dart';
import 'package:singular_flutter_sdk/singular_config.dart';
//...
class MyHomePage extends StatefulWidget {
//...
}
class _MyHomePageState extends State<MyHomePage> {
//...
@override
void initState() {
super.initState();
//...
SingularConfig config = new SingularConfig('SDK KEY', 'SDK SECRET');
// Set hashed User ID if available
config.customUserId = "b642b4217b34b1e8d3bd915fc65c4452";
// For iOS (Remove this if you are not displaying an ATT prompt)!
config.waitForTrackingAuthorizationWithTimeoutInterval = 300;
// To enable SkAdNetwork Support
config.skAdNetworkEnabled = true;
// To enable META Install Referrer
config.facebookAppId = "INSERT YOUR FACEBOOK APP ID HERE";
// (optional) Using Singular Global Properties feature to capture
// third party identifiers. The respective SDK(s) must be initialized
// before the Singular SDK. Example of passing the CleverTapID.
// var cleverTapId = CleverTapPlugin.getCleverTapID();
// config.withGlobalProperty("CLEVERTAPID", cleverTapId, true);
Singular.start(config);
}
处理 ATT 同意(设置初始化延迟)
显示 ATT(应用程序跟踪透明度)提示
从 iOS 14.5 开始,应用程序在访问和共享某些有助于追踪的用户数据(包括设备的IDFA)之前,必须征得用户同意(使用应用程序追踪透明度框架)。
拥有 IDFA 可以识别设备并执行安装归因,Singular 从中获益匪浅(不过也有不使用 IDFA 也能执行归因的方法)。我们强烈建议您征得用户同意获取 IDFA。
延迟初始化以等待 ATT 响应
默认情况下,Singular SDK 会在初始化时发送用户会话。当会话从新设备发送时,会立即触发 Singular 的归因流程--该流程仅根据 Singular 当时可用的数据执行。因此,在Singular SDK 发送第一个会话之前,必须征求同意并检索 IDFA。
要延迟启动用户会话,可在配置对象中使用waitForTrackingAuthorizationWithTimeoutInterval 选项初始化 Singular SDK。该选项已包含在上述代码示例中。
使用 Flutter 时,您需要依赖第三方软件包来实现应用程序跟踪透明度。例如:Flutter 的app_tracking_transparency插件。
提示:设置初始化延迟后,应用程序的流程如下:
- 应用程序打开时,Singular SDK 会开始记录会话和用户事件,但不会将其发送到 Singular 服务器。
- 当应用程序跟踪透明度同意被授予/拒绝,或设定的时间过去后,SDK 会将会话和任何排队的事件发送到 Singular 服务器(有或没有 IDFA)。
- 然后,Singular 会利用 IDFA(如果有的话)启动归属过程。
下表总结了使用此集成的可能方案:
方案 | IDFA 可用性 |
用户看到 "同意 "对话框,并在设定时间结束前授予 "同意"。 | IDFA 可用 |
用户看到同意对话框,并在设定时间结束前拒绝同意。 | IDFA 不可用 |
设定时间结束后,用户看到同意对话框并同意。 | IDFA 仅对同意后报告的用户事件有效 |
设置的时间已过,然后用户将看到同意对话框并拒绝同意。 | IDFA 不可用 |
用户看到同意对话框,未采取任何操作就退出了应用程序,然后在设定时间到期后打开应用程序并同意。 | 重新打开应用程序时,任何排队的事件都会发送到 Singular 服务器。IDFA 不能用于这些事件。同意后跟踪的任何事件都会有与之相关的 IDFA。 |
用户看到同意对话框后,未采取任何行动即退出应用程序,随后打开应用程序并拒绝同意。 | 重新打开应用程序时,任何排队的事件都会发送到 Singular 服务器。IDFA 不能用于这些事件或之后跟踪的任何事件。 |
添加 SKAdNetwork 支持
要为应用程序启用 SKAdNetwork 跟踪功能,请在初始化 Singular 之前启用skAdNetworkEnabled 配置选项。
托管模式(推荐)
在托管模式下,Singular 会根据您选择的转换模型自动为您管理 SKAdNetwork 转换值,您可以在 Singular 平台中设置该模型。
要了解更多信息,请参阅了解 Singular 的转换值管理和SKAdNetwork 模型配置常见问题。有关与 Singular 一起使用 SKAdNetwork 的分步指南,请参阅如何开始使用 SKAdNetwork。
注意:SKAN 托管模式已在上述初始化代码片段中启用。请确保已设置这些配置项。
要在托管模式下启用 SKAdNetwork,请使用以下代码:
SingularConfig config = new SingularConfig('<SDK KEY>', '<SDK SECRET>');
config.skAdNetworkEnabled = true;
config.waitForTrackingAuthorizationWithTimeoutInterval = 300;
Singular.init(config);
手动模式
如果您已经有自己的策略和工具来管理 SKAdNetwork 转换值,则可在手动模式下启用 SKAdNetwork。
SingularConfig config = new SingularConfig('SDK KEY', 'SDK SECRET');
config.skAdNetworkEnabled = true;
config.manualSkanConversionManagement = true;
config.waitForTrackingAuthorizationWithTimeoutInterval = 300;
Singular.init(config);
然后,使用以下代码更新转换值:
ingular.skanUpdateConversionValue(conversionValue)
要跟踪转换值的变化,请使用以下回调函数:
config.conversionValueUpdatedCallback = (int conversionValue) {
print('Received conversionValueUpdatedCallback: ' + conversionValue.toString());
};
要检索当前转换值,请使用以下代码:
Singular.skanGetConversionValue().then((conversionValue) {
print('conversion value: ' + conversionValue.toString());
});