Flutter SDK - SDK 方法参考

关注
Avatar
Jared Ornstead
Updated
文档

Flutter SDK - SDK 方法参考

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

广告收入

Singular.adRevenue 方法

通过详细的广告数据信息跟踪广告收入事件。通过该方法，您可以报告应用程序中显示的广告所产生的收入，并使用各种参数对广告性能进行分类和分析。

签名

static void adRevenue(SingularAdData? adData)

使用示例

// Create ad data object
final adData = SingularAdData("AdMob", "USD", 0.05)
    .withNetworkName("Google")
    .withAdType("Rewarded")
    .withAdPlacementName("level_complete")
    .withAdUnitId("ca-app-pub-123456789/1234567890");

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

清除全局属性

Singular.clearGlobalProperties 方法

删除所有先前设置的全局属性。这在需要重置全局属性时非常有用，例如当用户注销应用程序时。

签名

static void clearGlobalProperties()

使用示例

// Clear all global properties, for example when a user logs out
Singular.clearGlobalProperties();

createReferrerShortLink

Singular.createReferrerShortLink 方法

创建带有推荐人信息的短链接，可用于分享和归属。此方法可生成可与用户共享的可跟踪链接，从而将安装和活动归因于特定的推荐来源。

签名

static void createReferrerShortLink(String baseLink, String referrerName, String referrerId, Map args, ShortLinkCallback shortLinkCallback)

使用示例

// Create a short link for referral
Singular.createReferrerShortLink(
    "https://sample.sng.link/B4tbm/v8fp?_dl=https%3A%2F%2Fabc.com",
    "John Doe", // Referrer Name
    "aq239897", // Referrer ID
    {
        "channel": "sms", 
        "campaign": "summer_promo"
    }, // Passthrough parameters
    (String? data, String? error) {
        if (error != null) {
            print("Error creating short link: $error");
        } else {
            print("Generated short link: $data");
            // Share the link with users
        }
    }
);

自定义收入

Singular.customRevenue 方法

使用指定的事件名称、货币和金额跟踪自定义收入事件。这样就可以使用自定义名称跟踪收入事件，以获得更具体的收入跟踪。

  • 事件名称限制为 32 个 ASCII 字符。对于非 ASCII 字符，转换为 UTF-8 后，限制为 32 字节。

  • 货币代码必须为大写字母，并符合三个字母的ISO 4217货币代码

签名

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

使用示例

// Track a custom revenue event
Singular.customRevenue("premium_subscription", "USD", 9.99);

自定义收入与所有属性

Singular.customRevenueWithAllAttributes 方法

使用指定的事件名称、货币、金额和详细产品信息跟踪自定义收入事件。这样就可以通过产品详细信息进行全面的收入跟踪。

  • 事件名称限制为 32 个 ASCII 字符。对于非 ASCII 字符，转换为 UTF-8 后，限制为 32 字节。

  • 货币代码必须使用大写字母，并遵守三个字母的ISO 4217货币代码

签名

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

使用示例

// Track a custom revenue event with detailed product information
Singular.customRevenueWithAllAttributes(
    "item_purchased",
    "USD",
    19.98,
    "SKU123456",
    "Premium Sword",
    "Weapons",
    2,
    9.99
);

自定义收入属性

Singular.customRevenueWithAttributes 方法

使用指定的事件名称、货币、金额和其他自定义属性跟踪自定义收入事件。这允许使用自定义参数进行更详细的收入跟踪。

  • 事件名称限制为 32 个 ASCII 字符。对于非 ASCII 字符，转换为 UTF-8 后限制为 32 字节。

  • 货币代码必须为大写字母，并符合三个字母的ISO 4217货币代码

签名

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

使用示例

// Track a custom revenue event with additional parameters
Singular.customRevenueWithAttributes(
    "in_app_purchase",
    "USD",
    5.99,
    {
        "product_id": "com.app.gems_pack_small",
        "quantity": 1,
        "transaction_id": "T12345678",
        "receipt_id": "R98765432"
    }
);

事件

Singular.event 方法

跟踪具有指定名称的简单事件。使用该方法可跟踪应用程序中的用户操作和参与情况。

  • 事件名称限制为 32 个 ASCII 字符。对于非 ASCII 字符，转换为 UTF-8 后限制为 32 字节。

签名

static void event(String eventName)

使用示例

// Track a simple event
Singular.event("level_completed");

eventWithArgs

Singular.eventWithArgs 方法

跟踪具有指定名称和附加自定义属性的事件。这允许使用自定义参数进行更详细的事件跟踪。

  • 事件名称限制为 32 个 ASCII 字符。对于非 ASCII 字符，转换为 UTF-8 后限制为 32 字节。
  • 事件属性名称和属性值限制为 500 个 ASCII 字符。

签名

static void eventWithArgs(String eventName, Map args)

使用示例

// Track an event with additional parameters
Singular.eventWithArgs(
    "level_completed",
    {
        "level_id": 5,
        "score": 12500,
        "time_spent": 120,
        "difficulty": "medium"
    }
);

获取全局属性

Singular.getGlobalProperties 方法

读取当前设置的所有全局属性。该方法返回一个 Future，解析为一个 Map，其中包含已为 SDK 设置的所有全局属性。

签名

static Future getGlobalProperties()

使用示例

// Get all global properties
Singular.getGlobalProperties()

getLimitDataSharing

Singular.getLimitDataSharing 方法

读取当前的数据共享限制状态。此方法返回一个 Future，解析为一个布尔值，表示当前数据共享是否受限。

签名

static Future getLimitDataSharing()

使用示例

// Check if data sharing is limited
Singular.getLimitDataSharing()

handlePushNotification

Singular.handlePushNotification 方法

处理推送通知有效载荷，以确定归属。当应用程序收到推送通知时，应调用此方法，以便 Singular 对其进行正确归属。此方法仅适用于 iOS。

签名

static void handlePushNotification(Map pushNotificationPayload)

使用示例

// Handle a received push notification
void onPushNotificationReceived(Map payload) {
  Singular.handlePushNotification(payload);
}

inAppPurchase

Singular.inAppPurchase 方法

此方法需要使用Flutter IAP 包来管理应用程序中的交易。

使用指定的事件名称和购买数据跟踪应用内购买事件。该方法用于报告应用程序内的购买行为。

  • 事件名称限制为 32 个 ASCII 字符。对于非 ASCII 字符，转换为 UTF-8 后限制为 32 字节。

签名

static void inAppPurchase(String eventName, SingularIAP purchase)

使用示例

import 'package:in_app_purchase/in_app_purchase.dart';
import 'package:in_app_purchase_android/in_app_purchase_android.dart';
import 'package:in_app_purchase_storekit/in_app_purchase_storekit.dart';
import 'package:singular_flutter_sdk/singular_iap.dart';
import 'dart:io' show Platform;
import 'dart:convert'; // For JSON parsing
    
// Get product details
final response = await InAppPurchase.instance
   .queryProductDetails({purchaseDetails.productID});
if (response.productDetails.isEmpty) {
   return;
}

final product = response.productDetails.first;

// Prepare Singular purchase data
SingularIAP? singularPurchase;
const String eventName = 'iap_purchase'; // Must be <= 32 ASCII characters

if (Platform.isAndroid && purchaseDetails is GooglePlayPurchaseDetails) {
  singularPurchase = SingularAndroidIAP(
    product.rawPrice, // Price as a double, e.g., 4.99
    product.currencyCode ?? 'USD', // Currency code as String, e.g., "USD"
    purchaseDetails.billingClientPurchase.signature, // Signature from GooglePlayPurchase
    purchaseDetails.billingClientPurchase.originalJson, // Receipt Object from GooglePlayPurchase originalJson
  );
} else if (Platform.isIOS && purchaseDetails is AppStorePurchaseDetails) {
  singularPurchase = SingularIOSIAP(
    product.rawPrice, // Price as a double, e.g., 4.99
    product.currencyCode ?? 'USD', // Currency code as String, e.g., "USD"
    purchaseDetails.productID, // e.g., "com.example.premium_subscription"
    purchaseDetails.purchaseID ?? '', // transactionID from AppStorePurchaseDetails
    purchaseDetails.verificationData.serverVerificationData, // JWS receipt from StoreKit
  );
} else {
  return; // Unsupported platform
}

// Track with Singular
Singular.inAppPurchase(eventName, singularPurchase);

inAppPurchaseWithAttributes

Singular.inAppPurchaseWithAttributes 方法

此方法需要使用Flutter IAP 包来管理应用程序中的交易。

使用指定的事件名称、购买数据和其他自定义属性跟踪应用内购买事件。这允许使用自定义参数进行更详细的购买跟踪。

  • 事件名称限制为 32 个 ASCII 字符。对于非 ASCII 字符，转换为 UTF-8 后限制为 32 字节。

签名

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

使用示例

import 'package:in_app_purchase/in_app_purchase.dart';
import 'package:in_app_purchase_android/in_app_purchase_android.dart';
import 'package:in_app_purchase_storekit/in_app_purchase_storekit.dart';
import 'package:singular_flutter_sdk/singular_iap.dart';
import 'dart:io' show Platform;
import 'dart:convert'; // For JSON parsing
    
// Get product details
final response = await InAppPurchase.instance
   .queryProductDetails({purchaseDetails.productID});
if (response.productDetails.isEmpty) {
   return;
}

final product = response.productDetails.first;

// Prepare Singular purchase data
SingularIAP? singularPurchase;
const String eventName = 'iap_purchase'; // Must be <= 32 ASCII characters

if (Platform.isAndroid && purchaseDetails is GooglePlayPurchaseDetails) {
  singularPurchase = SingularAndroidIAP(
    product.rawPrice, // Price as a double, e.g., 4.99
    product.currencyCode ?? 'USD', // Currency code as String, e.g., "USD"
    purchaseDetails.billingClientPurchase.signature, // Signature from GooglePlayPurchase
    purchaseDetails.billingClientPurchase.originalJson, // Receipt Object from GooglePlayPurchase originalJson
  );
} else if (Platform.isIOS && purchaseDetails is AppStorePurchaseDetails) {
  singularPurchase = SingularIOSIAP(
    product.rawPrice, // Price as a double, e.g., 4.99
    product.currencyCode ?? 'USD', // Currency code as String, e.g., "USD"
    purchaseDetails.productID, // e.g., "com.example.premium_subscription"
    purchaseDetails.purchaseID ?? '', // transactionID from AppStorePurchaseDetails
    purchaseDetails.verificationData.serverVerificationData, // JWS receipt from StoreKit
  );
} else {
  return; // Unsupported platform
}

// Track the purchase with additional attributes
Singular.inAppPurchaseWithAttributes(
    eventName, 
    singularPurchase,
    purchase,
    {
        "user_level": 42,
        "is_first_purchase": true,
        "gems_balance": 1500
    }
);

isAllTrackingStopped

Singular.isAllTrackingStopped 方法

检查当前是否停止了所有跟踪。此方法返回一个 Future，解析为一个布尔值，表示当前是否停止了跟踪。

签名

static Future isAllTrackingStopped()

使用示例

// Check if tracking is stopped
Singular.isAllTrackingStopped()

limitDataSharing

Singular.limitDataSharing 方法

设置数据共享限制状态。使用该方法可根据用户同意或隐私要求限制数据共享。

签名

static void limitDataSharing(bool shouldLimitDataSharing)

使用示例

// To limit data sharing (e.g., when user opts out) 
Singular.limitDataSharing(true);

// To enable full data sharing (e.g., when user opts in)
Singular.limitDataSharing(false);

为卸载注册设备令牌

Singular.registerDeviceTokenForUninstall 方法

为卸载跟踪注册设备令牌。该方法应与推送通知令牌一起调用，以启用卸载跟踪。

签名

static void registerDeviceTokenForUninstall(String deviceToken)

使用示例

// Register device token for uninstall tracking
Singular.registerDeviceTokenForUninstall(token);

resumeAllTracking

Singular.resumeAllTracking 方法

恢复之前停止的所有跟踪活动。使用该方法可在停止跟踪后重新启用跟踪。

签名

static void resumeAllTracking()

使用示例

// Resume tracking, for example when user opts back in
Singular.resumeAllTracking();

setCustomUserId

Singular.setCustomUserId 方法

为当前用户设置自定义用户 ID。这样就可以将 Singular 数据与自己的用户识别系统关联起来。

签名

static void setCustomUserId(String customUserId)

使用示例

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

setDeviceCustomUserId

Singular.setDeviceCustomUserId 方法

在设备级别设置自定义用户 ID。这样就可以在设备级别将 Singular 数据与自己的用户识别系统关联起来。

签名

static void setDeviceCustomUserId(String customUserId)

使用示例

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

setFCMDeviceToken

Singular.setFCMDeviceToken 方法

为推送通知设置 Firebase Cloud Messaging（FCM）设备令牌。这用于在安卓设备上进行卸载跟踪和推送通知归属。

签名

static void setFCMDeviceToken(String fcmToken)

使用示例

// Set FCM token when received from Firebase
void onFCMTokenReceived(String token) {
    Singular.setFCMDeviceToken(token);
}

设置全局属性

Singular.setGlobalProperty 方法

设置将与所有事件一起发送的全局属性。这样，您就可以为所有事件添加一致的属性，而无需每次都指定这些属性。

签名

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

使用示例

// Set a global property
Singular.setGlobalProperty("user_tier", "premium", true).then((isSuccess) {
    print("Global property set successfully: $isSuccess");
});

skanGetConversionValue

Singular.skanGetConversionValue 方法

读取当前 SKAdNetwork 转换值。该方法是 iOS 特有的，返回一个 Future，解析为 SKAdNetwork 归属所用的当前转换值。

签名

static Future skanGetConversionValue()

使用示例

// Get the current SKAdNetwork conversion value
if (Platform.isIOS) {
    Singular.skanGetConversionValue().then((conversionValue) {
        print("Current conversion value: $conversionValue");
    });
}

skanRegisterAppForAdNetworkAttribution

Singular.skanRegisterAppForAdNetworkAttribution 方法

为 SKAdNetwork 归因注册应用程序。此方法专用于 iOS，应调用此方法启用 SKAdNetwork 归因。

签名

static void skanRegisterAppForAdNetworkAttribution()

使用示例

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

skanUpdateConversionValue

Singular.skanUpdateConversionValue 方法

更新 SKAdNetwork 转换值。该方法专用于 iOS，允许您手动更新用于 SKAdNetwork 归属的转换值。

签名

static Future skanUpdateConversionValue(int conversionValue)

使用示例

// Update the SKAdNetwork conversion value
if (Platform.isIOS) {
    Singular.skanUpdateConversionValue(5).then((isSuccess) {
        print("Conversion value updated successfully: $isSuccess");
    });
}

skanUpdateConversionValues

Singular.skanUpdateConversionValues 方法

使用附加参数更新 SKAdNetwork 转换值。此方法专用于 iOS 16.1+，允许您更新 SKAdNetwork 4.0 属性的精细、粗略和锁定值。

签名

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

使用示例

// Update the SKAdNetwork 4.0 conversion values
if (Platform.isIOS) {
    Singular.skanUpdateConversionValues(
        5,       // fine value (0-63)
        1,       // coarse value (0=low, 1=medium, 2=high)
        false    // lock
    );
}

开始

Singular.start 方法

使用提供的配置初始化 Singular SDK。这是开始使用 Singular SDK 时应该调用的第一个方法。

签名

static void start(SingularConfig config)

使用示例

// Create configuration object
SingularConfig config = new SingularConfig('SDK KEY', 'SDK SECRET');

// Configure additional options if needed
config.customUserId = "user-123456";
config.sessionTimeout = 60;

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

stopAllTracking

Singular.stopAllTracking 方法

停止所有跟踪活动。使用该方法可在用户选择退出或符合隐私保护规定时禁用跟踪。

签名

static void stopAllTracking()

使用示例

// Stop tracking, for example when user opts out.
Singular.stopAllTracking();

trackingOptIn

Singular.trackingOptIn 方法

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

签名

static void trackingOptIn()

使用示例

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

trackingUnder13

Singular.trackingUnder13 方法

表示用户未满 13 周岁。调用此方法可遵守 COPPA 和其他针对 13 岁以下用户的规定。

签名

static void trackingUnder13()

使用示例

// Notifies Singular the User is under 13 years old, GDPR_UNDER_13 flag applied.
Singular.trackingunder13();

unsetCustomUserId

Singular.unsetCustomUserId 方法

删除之前设置的自定义用户 ID。当用户注销或不想再将事件与当前用户 ID 关联时，调用此方法。

签名

static void unsetCustomUserId()

使用示例

// Clear custom user ID when user logs out
Singular.unsetCustomUserId();

unsetGlobalProperty

Singular.unsetGlobalProperty 方法

删除先前设置的全局属性。如果不想再通过事件发送特定全局属性，请调用此方法。

签名

static void unsetGlobalProperty(String key)

使用示例

// Remove a global property
Singular.unsetGlobalProperty("user_tier");