Flutter SDK - 配置方法参考

关注
Avatar
Jared Ornstead
Updated

Flutter SDK - 配置参考

本文档全面介绍了 Flutter 应用程序 Singular SDK 中的所有可用配置选项。通过 SingularConfig 对象，您可以自定义 SDK 的行为，包括跟踪设置、属性选项、隐私控制等。每个配置属性都附有说明、签名和实际使用示例。

brandedDomains

SingularConfig.brandedDomains 属性

SDK 应视为 Singular Links 的自定义链接域名。请添加您用于跟踪链接的所有品牌域名；否则只会识别 Manage Links 页面中登记的 sng.link 域名。默认值为空列表。

签名

List<String> brandedDomains

使用示例

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

SingularConfig config = SingularConfig('API_KEY', 'SECRET_KEY');
config.brandedDomains = ['go.yourcompany.com', 'promo.yourcompany.com'];

clipboardAttribution

SingularConfig.clipboardAttribution 属性

启用剪贴板属性，以跟踪复制到设备剪贴板的深度链接。启用后，SDK 将在应用程序启动时检查剪贴板中的 Singular 链接。

签名

bool clipboardAttribution

使用示例

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

SingularConfig config = SingularConfig('API_KEY', 'SECRET_KEY');
config.clipboardAttribution = true;

collectOAID

SingularConfig.collectOAID 属性

启用收集 Android 设备上的开放式匿名设备标识符（OAID）。OAID 是一种广告标识符，主要在中国使用。

签名

bool collectOAID

使用示例

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

SingularConfig config = SingularConfig('API_KEY', 'SECRET_KEY');
config.collectOAID = true;

conversionValueUpdatedCallback

SingularConfig.conversionValueUpdatedCallback 属性

设置 SKAdNetwork 转换值更新时触发的回调函数（仅限 iOS）。该回调接收新转换值作为参数。

签名

ConversionValueUpdatedCallback? conversionValueUpdatedCallback

使用示例

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

SingularConfig config = SingularConfig('API_KEY', 'SECRET_KEY');
config.conversionValueUpdatedCallback = (int conversionValue) {
  print('SKAdNetwork conversion value updated: $conversionValue');
};

conversionValuesUpdatedCallback

SingularConfig.conversionValuesUpdatedCallback 属性

设置 SKAdNetwork 4.0+ 转换值的回调函数（仅限 iOS 16.1+）。该回调接收精细转换值、粗略转换值和锁定状态。

签名

ConversionValuesUpdatedCallback? conversionValuesUpdatedCallback

使用示例

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

SingularConfig config = SingularConfig('API_KEY', 'SECRET_KEY');
config.conversionValuesUpdatedCallback = (int conversionValue, int coarse, bool lock) {
  print('Fine: $conversionValue, Coarse: $coarse, Locked: $lock');
};

customSdid

SingularConfig.customSdid 属性

设置自定义Singular设备 ID（SDID）。这允许你提供自己的设备标识符，而不是使用 SDK 生成的标识符。

签名

String? customSdid

使用示例

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

SingularConfig config = SingularConfig('API_KEY', 'SECRET_KEY');
config.customSdid = 'my_custom_device_id_123';

customUserId

SingularConfig.customUserId 属性

在 SDK 初始化过程中设置自定义用户标识符。这将从一开始就把所有事件与应用程序的用户 ID 关联起来。

签名

String? customUserId

使用示例

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

SingularConfig config = SingularConfig('API_KEY', 'SECRET_KEY');
config.customUserId = 'user_12345';

deviceAttributionCallback

BETA 功能 - 设置在设备归因数据可用时调用的回调函数。

SingularConfig.deviceAttributionCallback 属性

设置接收设备属性数据的回调函数。当 Singular 服务器提供属性信息时，将触发该回调。

仅包含有值的字段，因此读取前请先检查该键是否存在。大多数安装只会返回部分字段，具体包含哪些字段取决于 Singular 匹配到的触点。

键 类型 说明
network String 回调触发时始终包含。未匹配到触点时为 "Organic"。
campaign_id String 触点提供时包含。
campaign_name String 触点提供时包含。
subcampaign_id String 触点提供时包含。并非所有来源都会提供。
subcampaign_name String 触点提供时包含。并非所有来源都会提供。
creative_id String 触点提供时包含。并非所有来源都会提供。
creative_name String 触点提供时包含。并非所有来源都会提供。
passthrough String 链接附带透传值时包含。
match_type String 触点提供时包含。如需取值列表，请联系 Singular。
click_timestamp int 触点提供时包含。为 epoch 微秒，除以 1,000,000 可换算为秒。

签名

DeviceAttributionCallback? deviceAttributionCallback

使用示例

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

SingularConfig config = SingularConfig('API_KEY', 'SECRET_KEY');
config.deviceAttributionCallback = (Map<String, dynamic> attributes) {
  print('Attribution data received:');
  attributes.forEach((key, value) {
    print('  $key: $value');
  });
};

didSetSdidCallback

SingularConfig.didSetSdidCallback 属性

设置在 SDK 设置 Singular 设备 ID（SDID）后触发的回调函数。

签名

SdidAccessorCallback? didSetSdidCallback

使用示例

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

SingularConfig config = SingularConfig('API_KEY', 'SECRET_KEY');
config.didSetSdidCallback = (String sdid) {
  print('SDID has been set: $sdid');
};

enableLogging

SingularConfig.enableLogging 属性

启用 Singular SDK 的调试日志。启用后，SDK 将输出详细日志，帮助调试和排除故障。

签名

bool enableLogging

使用示例

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

SingularConfig config = SingularConfig('API_KEY', 'SECRET_KEY');
config.enableLogging = true;

enableOdmWithTimeoutInterval

SingularConfig.enableOdmWithTimeoutInterval 属性

启用具有指定超时间隔（秒）的设备上匹配（ODM）。ODM 在向 Singular 服务器发送数据之前，先在本地匹配设备标识符，从而提高归因的准确性。

签名

int enableOdmWithTimeoutInterval

使用示例

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

SingularConfig config = SingularConfig('API_KEY', 'SECRET_KEY');
config.enableOdmWithTimeoutInterval = 5; // 5 seconds timeout

espDomains

SingularConfig.espDomains 属性

包装您的 Singular Links 的电子邮件服务提供商（ESP）域名。当链接来自这些域名时，SDK 会跟随重定向还原出底层的 Singular Link，因此点击仍可归因。默认值为空列表。

签名

List<String> espDomains

使用示例

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

SingularConfig config = SingularConfig('API_KEY', 'SECRET_KEY');
config.espDomains = ['sl.esp.link', 'links.youresp.com'];

facebookAppId

SingularConfig.facebookAppId 属性

为 Facebook 归因整合设置 Facebook 应用程序 ID。这样就能对 Facebook 广告活动进行适当的归因跟踪。

签名

String? facebookAppId

使用示例

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

SingularConfig config = SingularConfig('API_KEY', 'SECRET_KEY');
config.facebookAppId = '1234567890123456';

globalProperties

SingularConfig.globalProperties 属性

在 SDK 初始化过程中设置全局属性列表。这些属性将自动包含在 SDK 跟踪的每个事件中。

签名

List<SingularGlobalProperty> globalProperties

使用示例

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

SingularConfig config = SingularConfig('API_KEY', 'SECRET_KEY');
config.globalProperties = [
  SingularGlobalProperty('app_version', '2.5.0', true),
  SingularGlobalProperty('user_tier', 'premium', false)
];

imei

SingularConfig.imei 属性

设置用于跟踪的设备 IMEI（国际移动设备标识）。 这主要用于某些亚洲市场，因为 IMEI 是常用的设备标识符。

签名

String? imei

使用示例

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

SingularConfig config = SingularConfig('API_KEY', 'SECRET_KEY');
config.imei = '123456789012345';

limitAdvertisingIdentifiers

SingularConfig.limitAdvertisingIdentifiers 属性

限制在 SDK 初始化过程中收集广告标识符（iOS 上为 IDFA，Android 上为 GAID）。启用后，SDK 将不会收集或传输广告 ID。

签名

bool limitAdvertisingIdentifiers

使用示例

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

SingularConfig config = SingularConfig('API_KEY', 'SECRET_KEY');
config.limitAdvertisingIdentifiers = true;

limitDataSharing

SingularConfig.limitDataSharing 属性

在 SDK 初始化期间限制与第三方共享数据。启用后，SDK 将限制与广告网络和其他合作伙伴共享属性数据。

签名

bool? limitDataSharing

使用示例

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

SingularConfig config = SingularConfig('API_KEY', 'SECRET_KEY');
config.limitDataSharing = true;

logLevel

SingularConfig.logLevel 属性

设置 SDK 的日志级别。数值越高，日志输出越详细，以便调试。

可用级别如下

  • 无 = -1

  • VERBOSE = Log.VERBOSE（Android 常量，数值 2）

  • DEBUG = Log.DEBUG (3)

  • INFO = Log.INFO (4)

  • WARNING = Log.WARN (5)

  • ERROR = Log.ERROR (6)

签名

int logLevel

使用示例

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

SingularConfig config = SingularConfig('API_KEY', 'SECRET_KEY');
config.logLevel = 5; // Maximum logging detail

manualSkanConversionManagement

SingularConfig.manualSkanConversionManagement 属性

启用手动 SKAdNetwork 转换值管理（仅限 iOS）。启用后，SDK 不会自动更新转换值，您可以完全控制转换值的设置时间和方式。

签名

bool manualSkanConversionManagement

使用示例

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

SingularConfig config = SingularConfig('API_KEY', 'SECRET_KEY');
config.manualSkanConversionManagement = true;

pushNotificationsLinkPaths

SingularConfig.pushNotificationsLinkPaths 属性

在推送通知载荷中查找 Singular Link 的位置。每个条目都是一组构成载荷路径的键，因此应用会收到几种载荷结构，就添加几个条目。默认值为 [[]]。

签名

List<List<String>> pushNotificationsLinkPaths

使用示例

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

SingularConfig config = SingularConfig('API_KEY', 'SECRET_KEY');
config.pushNotificationsLinkPaths = [
  ['sng_link'],                             // Top-level key
  ['data', 'url'],                          // Nested path
  ['rootObj', 'nestedObj', 'singularLink'], // Deep nested path
];

sdidReceivedCallback

SingularConfig.sdidReceivedCallback 属性

设置一个回调函数，当从服务器接收到或从本地存储检索到Singular设备 ID（SDID）时触发该函数。

签名

SdidAccessorCallback? sdidReceivedCallback

使用示例

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

SingularConfig config = SingularConfig('API_KEY', 'SECRET_KEY');
config.sdidReceivedCallback = (String sdid) {
  print('SDID received: $sdid');
};

sessionTimeout

SingularConfig.sessionTimeout 属性

设置会话超时时间（以秒为单位）。过了这段时间后，SDK 会在重新打开应用程序时将其视为一个新会话。

签名

double sessionTimeout

使用示例

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

SingularConfig config = SingularConfig('API_KEY', 'SECRET_KEY');
config.sessionTimeout = 60.0; // 60 seconds

shortLinkResolveTimeOut

SingularConfig.shortLinkResolveTimeOut 属性

设置解析短链接的超时时间（以秒为单位）。这决定了 SDK 在超时前等待短链接解析的时间。

签名

double shortLinkResolveTimeOut

使用示例

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

SingularConfig config = SingularConfig('API_KEY', 'SECRET_KEY');
config.shortLinkResolveTimeOut = 10.0; // 10 seconds

singularLinksHandler

SingularConfig.singularLinksHandler 属性

设置Singular链接（深度链接）的回调处理程序。当用户通过Singular短链接或延迟深度链接打开应用程序时，将触发该回调。

签名

SingularLinksHandler? singularLinksHandler

使用示例

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

SingularConfig config = SingularConfig('API_KEY', 'SECRET_KEY');
config.singularLinksHandler = (SingularLinkParams params) {
  print('Deep link received:');
  print('  Deep link: ${params.deeplink}');
  print('  Passthrough: ${params.passthrough}');
  print('  Is deferred: ${params.isDeferred}');
};

skAdNetworkEnabled

SingularConfig.skAdNetworkEnabled 属性

启用或禁用 SKAdNetwork 集成（仅限 iOS）。启用后，SDK 将自动处理 SKAdNetwork 归因和转换值更新。

签名

bool skAdNetworkEnabled

使用示例

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

SingularConfig config = SingularConfig('API_KEY', 'SECRET_KEY');
config.skAdNetworkEnabled = true;

waitForTrackingAuthorizationWithTimeoutInterval

SingularConfig.waitForTrackingAuthorizationWithTimeoutInterval 属性

设置在 iOS 上等待 App Tracking Transparency (ATT) 授权的超时间隔（以秒为单位）。SDK 将延迟初始化，直到用户回复 ATT 提示或达到超时时间。

签名

int waitForTrackingAuthorizationWithTimeoutInterval

使用示例

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

SingularConfig config = SingularConfig('API_KEY', 'SECRET_KEY');
config.waitForTrackingAuthorizationWithTimeoutInterval = 30; // 30 seconds

完整配置示例

下面是一个综合示例，展示了如何为 Flutter 应用程序配置 Singular SDK 的多个选项。

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

  void initSingularSDK() {
    // Create configuration object
    SingularConfig config = SingularConfig(
      'YOUR_API_KEY',
      'YOUR_SECRET_KEY'
    );

    // Enable logging for debugging
    config.enableLogging = true;
    config.logLevel = 4;

    // Set custom user ID if available
    config.customUserId = 'user_12345';

    // Configure session timeout
    config.sessionTimeout = 60.0;

    // Enable clipboard attribution
    config.clipboardAttribution = true;

    // Configure SKAdNetwork (iOS)
    config.skAdNetworkEnabled = true;
    config.manualSkanConversionManagement = false;
    config.waitForTrackingAuthorizationWithTimeoutInterval = 30;

    // Set conversion value callbacks (iOS)
    config.conversionValueUpdatedCallback = (int conversionValue) {
      print('SKAdNetwork conversion value updated: $conversionValue');
    };

    config.conversionValuesUpdatedCallback = (int cv, int coarse, bool lock) {
      print('SKAdNetwork values - Fine: $cv, Coarse: $coarse, Lock: $lock');
    };

    // Configure deep link handling
    config.singularLinksHandler = (SingularLinkParams params) {
      print('Singular Link detected');
      print('Deep link: ${params.deeplink}');
      print('Passthrough params: ${params.passthrough}');
      print('Is deferred: ${params.isDeferred}');

      // Handle deep link navigation
      if (params.deeplink != null) {
        // Navigate to appropriate screen based on deep link
      }
    };

    // Set short link timeout
    config.shortLinkResolveTimeOut = 10.0;

    // Configure attribution callback
    config.deviceAttributionCallback = (Map<String, dynamic> attributes) {
      print('Attribution data received:');
      attributes.forEach((key, value) {
        print('  $key: $value');
      });
    };

    // Configure SDID callbacks
    config.sdidReceivedCallback = (String sdid) {
      print('SDID received: $sdid');
    };

    config.didSetSdidCallback = (String sdid) {
      print('SDID has been set: $sdid');
    };

    // Set global properties
    config.globalProperties = [
      SingularGlobalProperty('app_version', '2.5.0', true),
      SingularGlobalProperty('user_tier', 'premium', false),
      SingularGlobalProperty('environment', 'production', true)
    ];

    // Configure Facebook integration
    config.facebookAppId = '1234567890123456';

    // Privacy settings
    config.limitDataSharing = false;
    config.limitAdvertisingIdentifiers = false;

    // Android-specific settings
    config.collectOAID = true;

    // Enable On-Device Matching
    config.enableOdmWithTimeoutInterval = 5;

    // Start the SDK
    Singular.start(config);

    print('Singular SDK initialized successfully');
  }

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Singular Flutter Demo',
      theme: ThemeData(
        primarySwatch: Colors.blue,
      ),
      home: Scaffold(
        appBar: AppBar(
          title: Text('Singular SDK Demo'),
        ),
        body: Center(
          child: Text('Singular SDK Initialized'),
        ),
      ),
    );
  }
}