文档

Flutter SDK - 方法参考

本综合参考文档记录了用于 Flutter 应用程序的 Singular SDK 中的所有可用方法。SDK 提供初始化、事件跟踪、收入报告、归因、数据隐私合规性和配置等功能。每种方法都附有说明、签名和实际使用示例，以帮助开发人员将 Singular SDK 功能集成到其 Flutter 应用程序中。

广告收入

Singular.adRevenue 方法

通过详细的广告数据信息跟踪广告收入事件。通过该方法，您可以报告应用程序中显示的广告所产生的收入，包括广告网络数据、位置信息和收入金额。

签名

static void adRevenue(SingularAdData adData)

使用示例

import 'package:singular_flutter_sdk/singular.dart';
import 'package:singular_flutter_sdk/singular_ad_data.dart';

// Create ad data object
SingularAdData adData = SingularAdData(
  'AdMob',
  'USD',
  0.99
)
  ..withAdPlatfom('Android')
  ..withAdType('Rewarded')
  ..withAdGroupId('group_123')
  ..withAdGroupName('Rewarded Video Group')
  ..withAdGroupType('rewarded_video')
  ..withImpressionId('impression_abc123')
  ..withAdPlacementName('main_menu')
  ..withAdUnitId('ca-app-pub-123456789')
  ..withAdUnitName('Main Menu Rewarded Video');

// Track the ad revenue
Singular.adRevenue(adData);

清除全局属性

Singular.clearGlobalProperties 方法

删除所有已设置的全局属性。全局属性是键值对，会自动添加到 SDK 跟踪的所有事件中。

签名

static void clearGlobalProperties()

使用示例

import 'package:singular_flutter_sdk/singular.dart';

// Clear all global properties
Singular.clearGlobalProperties();

createReferrerShortLink

Singular.createReferrerShortLink 方法

创建用于推荐跟踪的 Singular 短链接。该方法生成的短链接可供用户共享，以跟踪推荐属性。

签名

static void createReferrerShortLink(
  String baseLink,
  String referrerName,
  String referrerId,
  Map<String, String> passthroughParams,
  ShortLinkCallback completionHandler
)

使用示例

import 'package:singular_flutter_sdk/singular.dart';

// Create a referrer short link
Singular.createReferrerShortLink(
  'https://yourapp.sng.link/A1b2c',
  'John Doe',
  'user_12345',
  {
    'promo_code': 'SUMMER2025',
    'campaign': 'referral_program'
  },
  (String? shortLink, String? error) {
    if (error != null) {
      print('Error creating short link: $error');
    } else {
      print('Short link created: $shortLink');
    }
  }
);

自定义收入

Singular.customRevenue 方法

使用指定的事件名称、货币和金额跟踪自定义收入事件。该方法用于跟踪与应用内购买或广告收入无关的收入。

签名

static void customRevenue(
  String eventName,
  String currency,
  double amount
)

使用示例

import 'package:singular_flutter_sdk/singular.dart';

// Track custom revenue event
Singular.customRevenue('Subscription_Purchase', 'USD', 9.99);

customRevenueWithAttributes

Singular.customRevenueWithAttributes 方法

跟踪带有附加属性的自定义收入事件。该方法扩展了基本的自定义收入跟踪功能，允许您包含自定义键值对，以进行更详细的跟踪。

签名

static void customRevenueWithAttributes(
  String eventName,
  String currency,
  double amount,
  Map attributes
)

使用示例

import 'package:singular_flutter_sdk/singular.dart';

// Track custom revenue with additional attributes
Singular.customRevenueWithAttributes(
  'Premium_Upgrade',
  'USD',
  29.99,
  {
    'subscription_tier': 'premium',
    'billing_cycle': 'annual',
    'promotion_code': 'ANNUAL20'
  }
);

customRevenueWithAllAttributes

Singular.customRevenueWithAllAttributes 方法

跟踪带有所有可能属性（包括产品 SKU、产品名称、产品类别、产品数量和自定义属性）的自定义收入事件。

签名

static void customRevenueWithAllAttributes(
  String eventName,
  String currency,
  double amount,
  String productSKU,
  String productName,
  String productCategory,
  int productQuantity,
  Map attributes
)

使用示例

import 'package:singular_flutter_sdk/singular.dart';

// Track custom revenue with all attributes
Singular.customRevenueWithAllAttributes(
  'In_Game_Purchase',
  'USD',
  4.99,
  'gold_pack_500',
  'Gold Pack 500',
  'virtual_currency',
  1,
  {
    'payment_method': 'credit_card',
    'discount_applied': 'false'
  }
);

事件

Singular.event 方法

跟踪只有事件名称的简单事件。这是 Singular SDK 中最基本的事件跟踪形式。

签名

static void event(String eventName)

使用示例

import 'package:singular_flutter_sdk/singular.dart';

// Track a simple event
Singular.event('Level_Completed');

eventWithArgs

Singular.eventWithArgs 方法

使用键值对形式的附加属性跟踪事件。这样就可以使用自定义参数进行更详细的事件跟踪。

签名

static void eventWithArgs(String eventName, Map args)

使用示例

import 'package:singular_flutter_sdk/singular.dart';

// Track event with custom attributes
Singular.eventWithArgs('Level_Completed', {
  'level_number': 10,
  'score': 8500,
  'time_seconds': 245,
  'difficulty': 'hard'
});

获取全局属性

Singular.getGlobalProperties 方法

返回当前设置的所有全局属性的映射。全局属性会自动包含在 SDK 跟踪的每个事件中。

签名

static Future<Map<String, String>> getGlobalProperties()

使用示例

import 'package:singular_flutter_sdk/singular.dart';

// Get all global properties
Map<String, String> properties = await Singular.getGlobalProperties();
print('Current global properties: $properties');

getLimitDataSharing

Singular.getLimitDataSharing 方法

返回数据共享限制的当前状态。本方法检查当前是否限制与第三方共享数据。

签名

static Future<bool> getLimitDataSharing()

使用示例

import 'package:singular_flutter_sdk/singular.dart';

// Check if data sharing is limited
bool isLimited = await Singular.getLimitDataSharing();
print('Data sharing limited: $isLimited');

handlePushNotification

Singular.handlePushNotification 方法

处理推送通知属性。当您的应用程序收到推送通知时，应调用此方法，以便为通知驱动的应用程序打开启用归因跟踪。

签名

static void handlePushNotification(Map notification)

使用示例

import 'package:singular_flutter_sdk/singular.dart';

// Handle incoming push notification
Map<String, dynamic> notificationData = {
  'title': 'New Offer Available',
  'body': 'Check out our latest deals',
  'campaign_id': 'summer_2025'
};

Singular.handlePushNotification(notificationData);

inAppPurchase

Singular.inAppPurchase 方法

跟踪应用内购买事件。该方法向 Singular 报告应用程序内的购买行为，以便跟踪收入和归因。使用 Flutterin_app_purchase 包检索包含完整交易详细信息的购买对象。

SingularIAP purchase 对象必须使用平台特定子类构造函数构建：

SingularIOSIAP(double revenue, String? currencyCode, String? productId, String? transactionId, String? receipt)

SingularAndroidIAP(double revenue, String? currencyCode, String? signature, String? receipt)

因此，首先使用revenue 和currencyCode ，然后使用平台特定字段构建相应的SingularIAP 子类。

签名

static void inAppPurchase(String eventName, SingularIAP purchase)

使用示例

import 'package:singular_flutter_sdk/singular.dart';
import 'package:singular_flutter_sdk/singular_iap.dart';

// Build an iOS SingularIAP purchase object and send it to the SDK
const String eventName = 'iap_purchase'; // <= 32 ASCII chars
final SingularIAP purchase = SingularIOSIAP(
  4.99,               // revenue (double)
  'USD',              // currency code (String)
  'com.example.sku',  // productId (String)
  'transactionId123', // transactionID from AppStorePurchaseDetails (String)
  'base64_receipt'    // JWS receipt from StoreKit (String)
);

// OR, Build an Android SingularIAP purchase object and send it to the SDK
const String eventName = 'iap_purchase'; // <= 32 ASCII chars
final SingularIAP purchase = SingularAndroidIAP(
  4.99,               // revenue (double)
  'USD',              // currency code (String)
  'com.example.sku',  // Signature from GooglePlayPurchase (String)
  'originalJson_receipt'    // receipt Object from GooglePlayPurchase originalJson (String)
);

// Basic tracking
Singular.inAppPurchase(eventName, purchase);

inAppPurchaseWithAttributes（带属性的应用程序购买

Singular.inAppPurchaseWithAttributes 方法

跟踪带有附加自定义属性的应用内购买事件。该方法扩展了基本的 IAP 跟踪功能，允许自定义键值对，以进行更详细的购买跟踪。

签名

static void inAppPurchaseWithAttributes(String eventName, SingularIAP purchase, Map attributes)

使用示例

import 'package:singular_flutter_sdk/singular.dart';
import 'package:singular_flutter_sdk/singular_iap.dart';
// Generate SingularIAP purchase as above
// Tracking with attributes
  Singular.inAppPurchaseWithAttributes(eventName, purchase, {
    'user_level': 42,
    'is_first_purchase': true,
    'gems_balance': 1500
  });

isAllTrackingStopped

Singular.isAllTrackingStopped 方法

返回所有跟踪是否已停止。该方法检查 SDK 当前是否处于未收集或发送数据的状态。

签名

static Future<bool> isAllTrackingStopped()

使用示例

import 'package:singular_flutter_sdk/singular.dart';

// Check if tracking is stopped
bool isStopped = await Singular.isAllTrackingStopped();
print('All tracking stopped: $isStopped');

limitDataSharing

Singular.limitDataSharing 方法

限制或启用与第三方共享数据。该方法用于控制 SDK 是否与广告网络和其他第三方服务共享数据，以便进行归因分析。

签名

static void limitDataSharing(bool limitDataSharingValue)

使用示例

import 'package:singular_flutter_sdk/singular.dart';

// Limit data sharing
Singular.limitDataSharing(true);

// Or enable data sharing
Singular.limitDataSharing(false);

registerDeviceTokenForUninstall

Singular.registerDeviceTokenForUninstall 方法

为卸载跟踪注册设备的推送通知令牌，使 Singular 能够在用户卸载应用程序时进行检测。

签名

static void registerDeviceTokenForUninstall(String token)

使用示例

import 'package:singular_flutter_sdk/singular.dart';

// Register device token for uninstall tracking
String deviceToken = 'your_device_push_token_here';
Singular.registerDeviceTokenForUninstall(deviceToken);

resumeAllTracking

Singular.resumeAllTracking 方法

恢复之前停止的所有跟踪。该方法可在停止跟踪后重新启用数据收集和传输。

签名

static void resumeAllTracking()

使用示例

import 'package:singular_flutter_sdk/singular.dart';

// Resume tracking after it was stopped
Singular.resumeAllTracking();

setCustomUserId

Singular.setCustomUserId 方法

设置用于跟踪的自定义用户标识符。该方法将事件与应用程序用户系统中的特定用户 ID 关联。

签名

static void setCustomUserId(String customUserId)

使用示例

import 'package:singular_flutter_sdk/singular.dart';

// Set custom user ID after user logs in
Singular.setCustomUserId('user_12345');

setDeviceCustomUserId

Singular.setDeviceCustomUserId 方法

此方法已废弃，不再使用。

签名

static void setDeviceCustomUserId(String customUserId)

使用示例

import 'package:singular_flutter_sdk/singular.dart';

// Set device-level custom user ID
Singular.setDeviceCustomUserId('device_user_67890');

setFCMDeviceToken

Singular.setFCMDeviceToken 方法

设置 Firebase Cloud Messaging（FCM）设备令牌。该方法专门用于使用 FCM 进行推送通知的 Android 设备。

签名

static void setFCMDeviceToken(String token)

使用示例

import 'package:singular_flutter_sdk/singular.dart';
import 'dart:io';

// Set FCM token (Android only)
if (Platform.isAndroid) {
  String fcmToken = 'your_fcm_token_here';
  Singular.setFCMDeviceToken(fcmToken);
}

设置全局属性

Singular.setGlobalProperty 方法

设置将包含在所有后续事件中的全局属性。全局属性是自动添加到 SDK 跟踪的每个事件中的键值对。

签名

static void setGlobalProperty(
  String key,
  String value,
  bool overrideExisting
)

使用示例

import 'package:singular_flutter_sdk/singular.dart';

// Set a global property
Singular.setGlobalProperty('user_type', 'premium', true);
Singular.setGlobalProperty('app_theme', 'dark', false);

setLimitAdvertisingIdentifiers

Singular.setLimitAdvertisingIdentifiers 方法

限制收集广告标识符（iOS 上为 IDFA，Android 上为 GAID）。此方法控制 SDK 是否收集和使用广告 ID 进行归因。

签名

static void setLimitAdvertisingIdentifiers(bool limit)

使用示例

import 'package:singular_flutter_sdk/singular.dart';

// Limit advertising identifier collection
Singular.setLimitAdvertisingIdentifiers(true);

skanGetConversionValue

Singular.skanGetConversionValue 方法

获取当前 SKAdNetwork 转换值（仅限 iOS）。该方法检索已为 SKAdNetwork 归属设置的转换值。

签名

static Future<int> skanGetConversionValue()

使用示例

import 'package:singular_flutter_sdk/singular.dart';
import 'dart:io';

// Get current SKAdNetwork conversion value (iOS only)
if (Platform.isIOS) {
  int conversionValue = await Singular.skanGetConversionValue();
  print('Current conversion value: $conversionValue');
}

skanRegisterAppForAdNetworkAttribution

Singular.skanRegisterAppForAdNetworkAttribution 方法

将应用程序注册为 SKAdNetwork 归因（仅限 iOS）。调用此方法可在 iOS 设备上启用 SKAdNetwork 跟踪功能。

签名

static void skanRegisterAppForAdNetworkAttribution()

使用示例

import 'package:singular_flutter_sdk/singular.dart';
import 'dart:io';

// Register for SKAdNetwork attribution (iOS only)
if (Platform.isIOS) {
  Singular.skanRegisterAppForAdNetworkAttribution();
}

skanUpdateConversionValue

Singular.skanUpdateConversionValue 方法

更新 SKAdNetwork 转换值（仅限 iOS）。此方法为 SKAdNetwork 归因设置新的转换值，代表用户质量或参与程度。

签名

static void skanUpdateConversionValue(int conversionValue)

使用示例

import 'package:singular_flutter_sdk/singular.dart';
import 'dart:io';

// Update SKAdNetwork conversion value (iOS only)
if (Platform.isIOS) {
  Singular.skanUpdateConversionValue(5);
}

skanUpdateConversionValues

Singular.skanUpdateConversionValues 方法

使用附加参数更新 SKAdNetwork 转换值，包括粗转换值和锁定状态（仅限 iOS 16.1+）。该方法可对 SKAdNetwork 的回传进行更精细的控制。

签名

static void skanUpdateConversionValues(
  int conversionValue,
  int coarse,
  bool lock
)

使用示例

import 'package:singular_flutter_sdk/singular.dart';
import 'dart:io';

// Update conversion values with coarse value and lock (iOS 16.1+)
if (Platform.isIOS) {
  Singular.skanUpdateConversionValues(
    10,    // fine conversion value
    1,     // coarse conversion value
    false  // lock status
  );
}

开始

Singular.start 方法

使用提供的配置初始化并启动 Singular SDK。必须在调用其他 SDK 方法之前调用此方法，并且应在应用程序生命周期中尽早调用。

签名

static void start(SingularConfig config)

使用示例

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

// Create and configure the SDK
SingularConfig config = SingularConfig(
  'YOUR_API_KEY',
  'YOUR_SECRET_KEY'
)
  ..withLoggingEnabled()
  ..withSessionTimeoutInSec(60);

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

stopAllTracking

Singular.stopAllTracking 方法

停止 SDK 的所有跟踪。该方法会停止所有数据收集和传输，通常在用户选择退出跟踪时用于保护隐私。

签名

static void stopAllTracking()

使用示例

import 'package:singular_flutter_sdk/singular.dart';

// Stop all tracking (for privacy opt-out)
Singular.stopAllTracking();

trackingOptIn

Singular.trackingOptIn 方法

表示用户已选择接受跟踪。当用户明确同意数据跟踪和归因时，应调用此方法。

签名

static void trackingOptIn()

使用示例

import 'package:singular_flutter_sdk/singular.dart';

// User opted in to tracking
Singular.trackingOptIn();

trackingUnder13

Singular.trackingUnder13 方法

表示用户未满 13 周岁。该方法启用 COPPA 合规模式，限制收集 13 岁以下用户的数据。

签名

static void trackingUnder13()

使用示例

import 'package:singular_flutter_sdk/singular.dart';

// Enable COPPA compliance mode
Singular.trackingUnder13();

unsetCustomUserId

Singular.unsetCustomUserId 方法

删除自定义用户标识符。该方法会清除之前设置的自定义用户 ID，通常在用户注销时调用。

签名

static void unsetCustomUserId()

使用示例

import 'package:singular_flutter_sdk/singular.dart';

// Remove custom user ID on logout
Singular.unsetCustomUserId();

unsetGlobalProperty

Singular.unsetGlobalProperty 方法

按键删除特定全局属性。该方法清除先前设置的单个全局属性。

签名

static void unsetGlobalProperty(String key)

使用示例

import 'package:singular_flutter_sdk/singular.dart';

// Remove a specific global property
Singular.unsetGlobalProperty('user_type');