文档

跟踪应用程序内事件

跟踪应用内事件以分析营销活动绩效并衡量关键绩效指标 (KPI)，如用户登录、注册、教程完成或进度里程碑。

标准事件和属性

了解事件类型

Singular 支持两种类型的事件，以满足通用和特定应用程序的跟踪需求。

标准事件：由 Singular 识别并由广告网络支持的预定义事件（如sngLogin,sngContentView ），用于报告和优化。使用标准事件可简化设置，因为 Singular 会自动将其添加到 "事件 "列表中，无需手动定义。有关完整的事件名称和推荐属性，请参阅 "标准事件和属性列表"。
自定义事件：您的应用程序特有的事件（如Signup,AchievementUnlocked ），与 Singular 的标准事件不匹配。

建议尽可能使用标准事件，以便与广告网络兼容，并在 Singular 的事件列表中自动识别。

您的用户体验、营销或业务团队应根据企业的营销 KPI 编制事件列表。请参考《如何跟踪应用内事件》指南：Singular 归因客户指南》进行规划。

自定义事件限制

自定义事件有特定的字符和编码限制，以确保与第三方合作伙伴和分析解决方案的兼容性。

自定义事件限制：

语言：以英文传递事件名称和属性，以确保与第三方合作伙伴和分析解决方案的兼容性。
事件名称：限制为 32 个 ASCII 字符。非 ASCII 字符串转换为 UTF-8 时必须小于 32 字节
属性和值：限制为 500 个 ASCII 字符

发送事件

事件方法

使用event() 方法跟踪无附加属性的简单事件。

import 'package:singular_flutter_sdk/singular.dart';

// Track a simple custom event
Singular.event('SignUp');

// Track a standard event
Singular.event('sngLogin');

方法签名：

static void event(String eventName)

有关方法的完整列表，请参阅事件方法参考。

EventWithArgs 方法

跟踪带有附加自定义属性的事件，以提供更丰富的上下文，并在报告中进行详细的细分。

import 'package:singular_flutter_sdk/singular.dart';

// Track custom event with attributes
Singular.eventWithArgs('LevelComplete', {
  'level': 5,
  'score': 1250,
  'time_spent': 45.3
});

// Track standard event with recommended attributes
Singular.eventWithArgs('sngTutorialComplete', {
  'sngAttrContent': 'Flutter Basics',
  'sngAttrContentId': '32',
  'sngAttrContentType': 'video',
  'sngAttrSuccess': 'yes'
});

方法特征：

static void eventWithArgs(String eventName, Map args)

有关方法的完整列表，请参阅eventWithArgs 方法参考。

最佳实践

使用标准事件：首选标准事件，以便与广告网络兼容，并在 Singular 的事件列表中自动识别。
验证属性：发送前检查属性是否符合预期格式和字符限制
调试事件：在开发过程中启用 SDK 日志，以验证事件是否正确发送并在适当的时刻触发
与团队协调：与用户体验/营销团队合作，确保跟踪的事件与应用程序的 KPI 保持一致
在生产前进行测试：在开发环境中测试事件，以验证 Singular 控制面板中数据的准确性

跟踪应用内收入

跟踪来自应用内购买 (IAP)、订阅和自定义收入来源的收入，以衡量营销活动的绩效和广告支出回报率 (ROAS)。

收入数据通过三个渠道流动：

互动报告：在 Singular 面板中查看收入指标
导出日志：访问详细的 ETL 数据，进行自定义分析
实时回传：将收入事件发送到外部平台

为什么要跟踪收入事件？

丰富的分析功能：获取详细的交易数据，增强 Singular 报告
预防欺诈：包括交易收据（如来自 Google Play 或 Apple App Store 的收据），以验证购买并打击应用内欺诈行为
营销活动优化：将收入与营销工作挂钩，衡量投资回报率

最佳实践：传递完整的购买对象

我们强烈建议传递从安卓（Google Play Billing）或iOS（StoreKit）应用内购买（IAP）流程返回的购买对象。这样可以确保Singular收到全面的交易详细信息，包括

产品 ID
价格
货币
交易 ID
收据数据（用于验证）

通过传递完整的购买对象，您可以获得更丰富的报告，并利用 Singular 的欺诈检测功能，尤其是针对 Google Play 交易。

应用内购买集成

捕获 IAP 购买对象

使用 Flutter in_app_purchase 包检索包含完整交易详细信息的购买对象。

Flutter：使用in_app_purchase包访问 iOS StoreKit 和 Android Google Play Billing 购买详情

InAppPurchase 方法

跟踪带有购买详情的应用内购买事件，以验证收入和防止欺诈。

方法签名：

static void inAppPurchase(String eventName, SingularIAP purchase)

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

有关方法的完整列表，请参阅inAppPurchase 方法参考。

完整的 IAP 实现示例

实现完整的购买监听器，捕获 IAP 事件并将其发送到 Singular，同时发送特定于平台的购买对象。

import 'dart:io' show Platform;
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.dart';
import 'package:singular_flutter_sdk/singular_iap.dart';

Future<void> handlePurchase(PurchaseDetails purchaseDetails) async {
  if (purchaseDetails.status != PurchaseStatus.purchased &&
      purchaseDetails.status != PurchaseStatus.restored) {
    return;
  }

  final response = await InAppPurchase.instance
      .queryProductDetails({purchaseDetails.productID});
  if (response.productDetails.isEmpty) {
    return;
  }
  final product = response.productDetails.first;

  // Extract price and currency with platform-specific handling
  double price = 0.0;
  String currency = 'USD';

  if (Platform.isAndroid && product is GooglePlayProductDetails) {
    final offer = product.productDetails.oneTimePurchaseOfferDetails;
    price = (offer?.priceAmountMicros ?? 0) / 1000000;
    currency = offer?.priceCurrencyCode ?? 'USD';
  } else if (Platform.isIOS && product is AppStoreProductDetails) {
    price = product.skProduct.price;
    currency = product.skProduct.priceLocale.currencyCode ?? 'USD';
  }

  SingularIAP? singularPurchase;

  if (Platform.isAndroid && purchaseDetails is GooglePlayPurchaseDetails) {
    singularPurchase = SingularAndroidIAP(
      price,
      currency,
      purchaseDetails.billingClientPurchase.signature,
      purchaseDetails.billingClientPurchase.originalJson,
    );
  } else if (Platform.isIOS && purchaseDetails is AppStorePurchaseDetails) {
    singularPurchase = SingularIOSIAP(
      price,
      currency,
      purchaseDetails.productID,
      purchaseDetails.skPaymentTransaction.transactionIdentifier ?? '',
      purchaseDetails.verificationData.serverVerificationData,
    );
  } else {
    return;
  }

  const String eventName = 'iap_purchase';
  
  // Track with attributes (use only ONE tracking method)
  Singular.inAppPurchaseWithAttributes(eventName, singularPurchase, {
    'user_level': 42,
    'is_first_purchase': true,
    'gems_balance': 1500
  });

  await InAppPurchase.instance.completePurchase(purchaseDetails);
}

手动收入跟踪

无需购买验证的收入

通过传递货币、金额和可选产品详细信息来跟踪收入，而无需购买对象。请注意，此方法不提供用于验证的交易收据。

重要：在发送没有有效购买对象的收入事件时，Singular 不会验证交易。我们强烈建议尽可能使用上述inAppPurchase() 方法。

注意：以三个字母的 ISO 4217 货币代码形式传递货币，如USD,EUR,INR 。

自定义收入方法

使用指定的事件名称、货币和金额跟踪自定义收入事件。

import 'package:singular_flutter_sdk/singular.dart';

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

方法签名：

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

有关方法的完整列表，请参阅customRevenue 方法参考。

CustomRevenueWithAttributes 方法

使用指定的事件名称、货币、金额和其他自定义属性跟踪自定义收入事件。

import 'package:singular_flutter_sdk/singular.dart';

// Track custom revenue event with attributes
Singular.customRevenueWithAttributes('PremiumBundlePurchase', 'USD', 99.99, {
  'productSKU': 'premium_bundle_xyz',
  'productName': 'Premium Bundle',
  'productCategory': 'Bundles',
  'productQuantity': 1,
  'discount_applied': true
});

方法签名：

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

有关方法的完整列表，请参见customRevenueWithAttributes 方法参考。

CustomRevenueWithAllAttributes 方法

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

import 'package:singular_flutter_sdk/singular.dart';

// Track custom revenue with all attributes
Singular.customRevenueWithAllAttributes(
  'CoinPackagePurchase',
  'USD',
  4.99,
  'coin_package_abc123',
  'Coin Pack 10',
  'Virtual Currency',
  2,
  {
    'payment_method': 'google_play',
    'transaction_id': 'T12345'
  }
);

方法签名：

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

有关方法的完整列表，请参见customRevenueWithAllAttributes 方法参考。

订阅收入

跟踪订阅

Singular 提供了使用 Singular SDK 实现订阅事件的综合指南。该指南涵盖跨各种平台的应用内订阅事件跟踪。

如果您想跟踪订阅收入，请阅读《订阅事件技术实施指南

混合事件跟踪（高级）

Singular 建议通过集成到应用程序中的 Singular SDK 发送所有事件和收入，以获得最佳归因。不过，必要时，Singular 也可以从其他来源收集事件。

在Singular SDK之外发送的事件必须符合Singular的服务器到服务器事件文档要求，并提供匹配的设备标识符，以便正确归因。

重要：

如果服务器到服务器事件请求中使用的设备标识符在 Singular 中没有匹配的设备标识符，就会出现差异。请注意以下可能性：

早期事件：如果在Singular SDK 从应用程序会话中记录设备标识符之前收到事件请求，事件请求将被视为未知设备的 "第一次会话"，Singular 将把设备归属为有机归属。
不匹配的标识符：如果Singular SDK记录了设备标识符，但与服务器到服务器事件请求中指定的设备标识符不同，则事件将被错误归属

混合事件跟踪指南

从内部服务器发送事件

从内部服务器收集收入数据，分析营销活动的绩效和投资回报率。

要求：

捕获设备标识符：从应用内注册或登录事件中捕获并传递设备标识符，并将此数据与服务器上的用户 ID 一起存储。由于用户的设备标识符可能会发生变化，因此应在用户生成应用程序会话时更新标识符。这将确保服务器端事件归属于正确的设备
平台特定标识符：服务器端事件是平台特定的，只能使用与设备平台相匹配的设备标识符发送（例如，iOS 设备使用 IDFA 或 IDFV，Android 设备使用 GAID）
实时更新：使用奇异内部商业智能回传机制将事件实时推送到内部端点，以便在服务器端更新数据集。请参阅内部 BI 回传常见问题
实施细节：查看服务器到服务器集成指南中的 "跟踪收入"部分，了解详情

从收入提供商发送事件

集成 RevenueCat 或 adapty 等第三方收入提供商，向 Singular 发送购买和订阅收入。

支持的供应商：

RevenueCat：在RevenueCat 文档中了解更多信息
adapty：在adapty 文档中了解更多信息

从Segment发送事件

通过在Segment中添加 "云模式 "目标，使Segment能够与Singular SDK并行发送事件到Singular。

详细设置说明请参阅Singular-Segment Integration实施指南。

Flutter SDK - 跟踪应用程序内事件

跟踪应用程序内事件

标准事件和属性

了解事件类型

自定义事件限制

发送事件

事件方法

EventWithArgs 方法

最佳实践

跟踪应用内收入

为什么要跟踪收入事件？

应用内购买集成

捕获 IAP 购买对象

InAppPurchase 方法

完整的 IAP 实现示例

手动收入跟踪

无需购买验证的收入

自定义收入方法

CustomRevenueWithAttributes 方法

CustomRevenueWithAllAttributes 方法

订阅收入

跟踪订阅

混合事件跟踪（高级）

混合事件跟踪指南

从内部服务器发送事件

从收入提供商发送事件

从Segment发送事件