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 方法
使用指定的事件名称、货币和金额跟踪自定义收入事件。这样就可以使用自定义名称跟踪收入事件，以获得更具体的收入跟踪。
签名
static void customRevenue(String eventName, String currency, double amount)使用示例
// Track a custom revenue event
Singular.customRevenue("premium_subscription", "USD", 9.99);自定义收入与所有属性
Singular.customRevenueWithAllAttributes 方法
使用指定的事件名称、货币、金额和详细产品信息跟踪自定义收入事件。这样就可以通过产品详细信息进行全面的收入跟踪。
签名
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 方法
使用指定的事件名称、货币、金额和其他自定义属性跟踪自定义收入事件。这允许使用自定义参数进行更详细的收入跟踪。
签名
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:singular_flutter_sdk/singular_iap.dart';
singularPurchase = new SingularIOSIAP(
product.price,
product.currencyCode,
purchase.productId,
purchase.purchaseId,
purchase.verificationData.serverVerificationData);
singularPurchase = new SingularAndroidIAP(
product.price,
product.currencyCode,
purchase.singature,
purchase.verificationData.serverVerificationData);
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:singular_flutter_sdk/singular_iap.dart';
singularPurchase = new SingularIOSIAP(
product.price,
product.currencyCode,
purchase.productId,
purchase.purchaseId,
purchase.verificationData.serverVerificationData);
singularPurchase = new SingularAndroidIAP(
product.price,
product.currencyCode,
purchase.singature,
purchase.verificationData.serverVerificationData);
// 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");