基本整合

新功能:视频指南

观看视频,详细了解集成过程。我们建议您同时使用视频和下面的书面指南。

开始之前: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,请勿添加此权限。

注意:如果您的应用程序拥有android.permission.GET_TASKS权限,则应用程序可能会在用户实际打开之前被初始化。这可能会初始化 Singular SDK 并导致安装时间不一致。为防止出现这种问题,如果不需要该权限,请将其删除,或者将 Singular SDK 初始化调用移到代码中的其他地方,确保只有在用户首次打开应用程序后才调用该调用。

iOS 的其他步骤

要使用 Singular 插件,必须添加 AdServices 框架。


初始化 Singular SDK

每次打开应用程序时,都应调用 Singular SDK 初始化代码。这是所有 Singular 归因功能的前提条件,它还会向 Singular 发送一个新的用户会话(会话用于计算用户留存)。

初始化代码位于应用程序的主窗口部件(即 main.dart)中,也就是应用程序打开时加载的第一个窗口部件。该部件必须是有状态的,代码必须添加到部件的initState()方法中。

  1. 首先,你必须创建一个 SingularConfig 对象。该对象包含你的 Singular SDK 密钥和秘密。
  2. 您还可以选择添加设置,以启用各种 SDK 功能。请参阅完整的选项列表
  3. META 安装推荐人归属支持

    启用"元安装推荐人 "属性所需的 SDK 配置

    1. 在奇异配置对象中提供您的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插件。

提示:设置初始化延迟后,应用程序的流程如下:

  1. 应用程序打开时,Singular SDK 会开始记录会话和用户事件,但不会将其发送到 Singular 服务器。
  2. 当应用程序跟踪透明度同意被授予/拒绝,或设定的时间过去后,SDK 会将会话和任何排队的事件发送到 Singular 服务器(有或没有 IDFA)。
  3. 然后,Singular 会利用 IDFA(如果有的话)启动归属过程。
了解所有可能的 ATT 场景

下表总结了使用此集成的可能方案:

方案 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());
});