Singular SDK 可作为 Flutter 的插件使用。以下说明将向您介绍如何将 Singular 集成到您的 Flutter 应用程序中。

前提条件

• 本文假设您有一个功能完善的 Flutter 应用程序。
• 要初始化 SDK，您需要 Singular SDK Key 和 SDK Secret。您可以在 Singular 平台的"开发工具 > SDK 集成 > SDK 密钥"中获取它们。

集成 Singular 插件

要在 Flutter 应用程序中添加 Singular 插件，请在pubspec.yaml文件中添加以下几行：

dependencies:
  singular_flutter_sdk: ^1.4.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'

添加权限

在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" />

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。该选项已包含在上述代码示例中。

向 Singular 发送用户 ID（可选）

您可以使用 Singular SDK 方法向 Singular 发送内部用户 ID。

• 用户 ID 可以是任何标识符，但不应暴露 PII（个人身份信息）。例如，不应使用用户的电子邮件地址、用户名或电话号码。Singular 建议使用仅对第一方数据唯一的哈希值。
• 传递给Singular的用户ID值也应该是你在所有平台（Web/移动/PC/控制台/离线）上获取的相同的内部用户ID。
• Singular 将在用户级导出、ETL 和内部 BI 回传（如果配置）中包含用户 ID。用户 ID 是第一方数据，Singular 不会与其他方共享。
• 使用 Singular SDK 方法设置的用户 ID 值将一直存在，直到使用unsetCustomUserId 方法取消设置或卸载应用程序为止。关闭或重启应用程序不会取消设置用户 ID。

要设置用户 ID，请使用setCustomUserId 方法。要取消设置（例如，如果用户 "注销 "账户），请致电unsetCustomUserId 。

如果已经知道应用程序打开时的用户 ID，请在初始化 Singular SDK 之前调用setCustomUserId 。这样，Singular 就能从第一次会话中获得用户 ID。不过，在用户注册或登录之前，用户 ID 通常是不可用的。在这种情况下，请在注册流程完成后调用setCustomUserId 。

Singular.setCustomUserId("custom_user_id");

Singular.unsetCustomUserId();

Singular.setDeviceCustomUserId("custom_user_id");

实现深度链接

深度链接是在用户手机上打开应用程序并直接将用户发送到特定页面或用户体验的链接，而不仅仅是应用程序的主窗口小部件。深度链接通常用于重定向营销活动，目标用户是手机中已经安装了应用程序但可能有一段时间没有使用的用户。Singular 支持通过 Singular Links 进行深度链接。

启用奇异链接

要在 iOS 和 Android 中启用 Singular Links，请参阅Singular Links Prerequisites。

要支持 Android，请在项目的MainActivity.java文件中添加以下代码：

import com.singular.flutter_sdk.SingularBridge;
import android.content.Intent;

@Override
protected void onNewIntent(@NonNull Intent intent) {
  super.onNewIntent(intent);
  SingularBridge.onNewIntent(intent);
}

import com.singular.flutter_sdk.SingularBridge;
import android.content.Intent;

override fun onNewIntent(intent: Intent) {
  super.onNewIntent(intent)
  SingularBridge.onNewIntent(intent);
}

对于iOS 支持，在项目的 AppDelegate.m 中添加以下内容：

// Top of AppDelegate.m
            
#import "SingularAppDelegate.h"

- (BOOL)application:(UIApplication *)application 
     didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
       [GeneratedPluginRegistrant registerWithRegistry:self];
       [SingularAppDelegate shared].launchOptions = launchOptions;
       return [super application:application 
         didFinishLaunchingWithOptions:launchOptions];
}

- (BOOL)application:(UIApplication *)application 
     continueUserActivity:(NSUserActivity *)userActivity 
     restorationHandler:(void (^)(NSArray<id<UIUserActivityRestoring>> 
       *restorableObjects))restorationHandler {
         [[SingularAppDelegate shared] continueUserActivity:userActivity 
           restorationHandler:restorationHandler];
     return [super application:application continueUserActivity:userActivity 
         restorationHandler:restorationHandler ];
}

- (BOOL)application:(UIApplication *)app 
     openURL:(NSURL *)url 
     options:(NSDictionary<UIApplicationOpenURLOptionsKey,id> *)options {
       [[SingularAppDelegate shared] handleOpenUrl:url options:options];
       return [super application:app openURL:url options: options];
}

import singular_flutter_sdk
  
override func application(_ application: UIApplication, 
  didFinishLaunchingWithOptions
  launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
    GeneratedPluginRegistrant.register(with: self) if 
      let singularAppDelegate = SingularAppDelegate.shared() {
        singularAppDelegate.launchOptions = launchOptions
      }
  return super.application(application, didFinishLaunchingWithOptions:launchOptions)
}

override func application(_ application: UIApplication, 
  continue userActivity:NSUserActivity, 
  restorationHandler: @escaping ([UIUserActivityRestoring]?)-> Void) -> Bool {
    if let singularAppDelegate = SingularAppDelegate.shared() {
      singularAppDelegate.continueUserActivity(userActivity, restorationHandler:nil)
    }
  return super.application(application, continue:userActivity, 
    restorationHandler: restorationHandler);
}

override func application(_ app: UIApplication, 
  open url: URL, options:[UIApplication.OpenURLOptionsKey : Any] = [:]) -> Bool {
    if let singularAppDelegate = SingularAppDelegate.shared() {
      singularAppDelegate.handleOpen(url, options: options)
    }
  return super.application(app, open: url, options: options);
}

处理 Singular 链接

使用 Singular 的处理机制来读取导致应用程序被打开的跟踪链接的详细信息。

例如

SingularConfig config = new SingularConfig('<SDK KEY>', '<SDK SECRET>');

config.singularLinksHandler = (SingularLinkParams params) {
  String deeplink = params.deeplink;
  String passthrough = params.passthrough;
  bool isDeferred = params.isDeferred;
  // Add your code here to handle the deep link
};
          
Singular.init(config);

跟踪事件（非收入）

Singular 可以收集有关应用程序内事件的数据，帮助分析营销活动的绩效并衡量关键绩效指标。例如，您的企业可能希望收集有关用户登录、注册、教程完成或游戏应用中等级提升的数据。

Singular 支持各种 标准事件。广告网络通常支持这些常用事件，以便进行报告和优化。另一个优点是，当你使用标准事件名称时，Singular 会自动识别并将其添加到事件列表中，而无需手动定义。我们建议尽可能使用标准事件。

发送到 Singular 的事件列表（附带属性）应由用户体验/营销/业务团队根据企业的营销关键绩效指标编制。业务团队可参考《如何跟踪应用内事件》指南：单一归因客户指南》。

您跟踪的每个事件都可以传递各种属性。请参阅推荐的每个事件的标准属性。

在代码中，使用 event 或 eventWithArgs 方法向 Singular 发送事件。

例如

Singular.event(Events.sngLogin);
Singular.eventWithArgs(eventName, {attributeName:attributeValue});
Map<String, Object> map = HashMap<String, Object>();
map ['name'] = 'John Doe';
map ['age'] = 30;
map ['isStudent'] = false;
Singular.eventWithArgs('event_Name', map);

跟踪收入

发送 IAP 事件

要让 Singular 跟踪应用程序的收入情况，请向 Singular 发送 IAP 事件。通过发送 IAP 事件，您还可以让 Singular 检查事件验证数据，确保它不是欺诈性的。

请参阅以下示例。

注：此代码片段需要 Flutter IAP 软件包，请访问https://pub.dev/packages/in_app_purchase。

import 'package:singular_flutter_sdk/singular_iap.dart';
import 'dart:io' show Platform;
            
if (Platform.isIOS) {
  singularPurchase = new SingularIOSIAP(
    product.rawPrice.toStringAsFixed(2),
    product.currencyCode,
    purchase.productID,
    purchase.purchaseID,
    purchase.verificationData.serverVerificationData
  );
}
            
else if (Platform.isAndroid) {
  singularPurchase = new SingularAndroidIAP(
    product.rawPrice.toStringAsFixed(2),
    product.currencyCode,
    purchase.verificationData.serverVerificationData,
    purchase.verificationData.localVerificationData
  );
}
            
Singular.inAppPurchase(eventName, singularPurchase);

替代方法：发送自定义收入事件

Singular 也提供报告收入的选项，只需发送带有名称和收入金额的自定义收入事件即可。请注意，这种方法不会与 Singular 共享购买收据，因此无法让 Singular 验证这是一个合法的事件。

例如

Singular.customRevenue("MyCustomRevenue", "USD", 5.50);
Map<String, Object> map = HashMap<String, Object>();
map ['name'] = 'John Doe';
map ['age'] = 30;
map ['isStudent'] =false;
Singular.customRevenueWithAttributes('MyCustomRevenue','USD', 20, map);

混合事件跟踪（高级）

Singular 建议通过集成到应用程序中的 Singular SDK 发送所有事件和收入。但是，Singular 也可以从其他来源收集事件和收入。

任何未从 Singular SDK 发送的事件都必须符合 Singular 的服务器到服务器事件文档要求，并提供匹配的设备标识符，以便正确归属事件。

混合事件跟踪指南

添加广告收入归属支持

添加 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());
});

其他选项

跟踪卸载

要让Singular跟踪应用程序卸载情况，请向Singular提供APNS/FCM令牌，如下例所示：

// iOS
Singular.registerDeviceTokenForUninstall(apnsToken);
            
// Android
Singular.registerDeviceTokenForUninstall(fcmToken);

遵守数据隐私法

Singular提供隐私保护功能，帮助您与任何可能遵守消费者隐私法（如GDPR和CCPA（加州消费者隐私法））的合作伙伴合作。这些合作伙伴希望在最终用户同意共享其私人信息时得到通知。

如果你已经实施了一种征求用户同意共享其信息的方法，请使用limitDataSharing方法将用户的选择通知 Singular：

使用Singular.limitDataSharing(false)表示用户同意（选择加入）共享信息。

如果用户不同意，则使用Singular.limitDataSharing(true)。

Singular会在"用户隐私回传"（User Privacy Postbacks）中使用限制数据分享（LimitDataSharing）功能，并将此信息传递给需要的合作伙伴，以遵守相关法规。更多信息请参阅"用户隐私和限制数据共享"。

// User has opted into sharing data
Singular.limitDataSharing(false);

遵守 GDPR 的其他方法

Singular SDK 提供了多种方法来帮助您遵守 GDPR 政策，并让 Singular 了解用户是否同意追踪。

Singular.trackingOptIn();

Singular.stopAllTracking();

Singular.resumeAllTracking();

Singular.isAllTrackingStopped();