Flutter SDK - 配置方法参考

关注
Avatar
Jared Ornstead
Updated
文档

Flutter SDK - 配置参考

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

剪贴板属性

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 属性

设置自定义奇异设备 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';

自定义用户 ID

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

SingularConfig.deviceAttributionCallback 属性

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

签名

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');
};

启用记录

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

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;

日志级别

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;

sdidReceivedCallback

SingularConfig.sdidReceivedCallback 属性

设置一个回调函数，当从服务器接收到或从本地存储检索到奇异设备 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');
};

会话超时

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 属性

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

签名

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'),
        ),
      ),
    );
  }
}