Flutter SDK - 基础集成

文档
新增:视频指南

观看此视频,详细了解集成流程。 我们建议 您同时参考视频和下方的文字指南。

先决条件

在安装 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 依赖项

  1. 更新 pubspec.yaml:在项目的pubspec.yaml 文件中 添加 Singular Flutter SDK 依赖项:
    pubspec.yaml
    dependencies:
      flutter:
        sdk: flutter
      singular_flutter_sdk: ^1.8.0
  2. 安装依赖项:在终端中导航至项目目录, 并运行:
    bash
    flutter packages get

平台配置

iOS 配置

完成 iOS 特定的设置,以启用 AdServices 框架对 iOS 归因跟踪的支持。

添加 AdServices 框架

Apple Search Ads 归因 以及 iOS 14.3 及以上版本的 SKAdNetwork 集成需要 AdServices 框架。

  1. 导航至 iOS 项目:打开 Flutter 项目的 iOS 目录,找到 Xcode 工作区。
    • 导航至 Flutter 项目的ios 文件夹。
    • 在 Xcode 中打开Runner.xcworkspace (若使用 CocoaPods,请使用 .xcworkspace ;否则 请使用.xcodeproj )。
  2. 添加 AdServices 框架:在 Xcode 项目设置中配置该框架。
    • 在 Xcode 中,选择您的项目目标(例如“Runner”)。
    • 转到“通用”选项卡。
    • 滚动至 “框架、库和嵌入式内容” 部分。
    • 点击“+”按钮。
    • 搜索AdServices.framework 并添加它。
    • 将框架状态设置为“可选”(确保 与旧版 iOS 兼容)。

为何选择“可选”?将 AdServices 设为可选可确保 您的应用与未包含 此框架的 iOS 版本(iOS 14.2 及更早版本)保持兼容。

Android 配置

配置您的 Android 构建文件,以添加必要的权限和依赖项, 确保 SDK 功能正常运行。

添加所需权限

在 `AndroidManifest.xml ` 文件中的 `<manifest> ` 标签下添加这些权限,以启用 SDK 核心功能。

AndroidManifest.xml
<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 中添加以下内容:

AndroidManifest.xml
<queries>
   <package android:name="com.sec.android.app.samsungapps" />
</queries>

传递性依赖项

如果您已在 Gradle 配置中禁用了 Singular SDK 的 传递性依赖,请手动添加以下必需依赖项:

android/app/build.gradle
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 在生产环境中可能无法正常运行。

  1. 查找 ProGuard 文件:在您的 Flutter 项目中导航至 android/app/proguard-rules.pro
  2. 添加保留规则:在文件末尾添加以下规则以保留 SDK 类:
    android/app/proguard-rules.pro
    # 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 类。

Dart
import 'package:singular_flutter_sdk/singular.dart';
import 'package:singular_flutter_sdk/singular_config.dart';

初始化 SDK

使用您的 SDK 凭据创建一个SingularConfig 对象, 配置可选功能,并使用 start() 方法初始化 SDK。

基本初始化

  1. 获取凭据:登录您的 Singular账户 并导航至 开发者工具 > SDK 集成 > SDK密钥 以查找您的 SDK 密钥和密钥密文。
  2. 创建配置:使用凭据实例化 SingularConfig 对象。
  3. 添加配置:可选地使用归因设置器配置 SDK 行为 (参见 配置参考)。
  4. 初始化 SDK:调用Singular.start() 以启动 SDK。

初始化示例

在应用的入口点初始化 SDK,通常位于 主 StatefulWidget 的initState() 方法中。

Dart
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 对象设置额外的 归因。

Dart
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 实现阶段 完成此配置,以避免返工。

参阅完整的 iOS ICM 技术要求