跟踪应用内事件

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

标准事件和属性

了解事件类型

Singular 支持两种类型的事件，以满足通用和应用专属的跟踪需求。

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

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

您的用户获取 (UA)、市场营销或业务团队应根据组织的营销 KPI 汇总事件列表。有关规划方面的指导，请参阅如何跟踪应用内事件：Singular 归因客户指南。

自定义事件限制

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

自定义事件限制：

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

发送事件

Event 方法

使用 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)

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

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 日志记录，以验证事件是否正确发送并在适当的时机触发
与团队协调： 与您的 UA/市场营销团队合作，确保所跟踪的事件与应用的 KPI 保持一致
在生产环境前进行测试： 在开发环境中测试事件，以验证 Singular 控制台中的数据准确性

跟踪应用内收入

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

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

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

为什么要跟踪收入事件？

丰富的分析： 捕获详细的交易数据，以增强 Singular 报告
欺诈防范： 包含交易收据（例如来自 Google Play 或 Apple App Store 的收据）以验证购买并打击应用内欺诈
广告系列优化： 通过将收入与营销活动关联来衡量 ROI

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

我们强烈建议传递从 Android（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);
}

手动收入跟踪

无购买验证的收入

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

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

注意： 请以三字母 ISO 4217 货币代码传递货币，例如 USD 、 EUR 、 INR 。

CustomRevenue 方法

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

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 实现订阅事件。该指南涵盖了跨各种平台的应用内订阅事件跟踪。

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

混合事件跟踪（高级）

CDP 和第三方集成不兼容： SDID 与 CDP（Segment、mParticle、RudderStack）或第三方订阅提供商（RevenueCat、Adapty）不兼容。如果启用了 SDID，则无法并行使用这些平台进行事件转发，这会导致归因不完整或中断。

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

在 Singular SDK 之外发送的事件必须符合 Singular 的 Server-to-Server 事件文档要求，并提供匹配的设备标识符以实现正确归因。

重要提示：

如果 Server-to-Server 事件请求中使用的设备标识符在 Singular 中没有匹配的设备标识符，则会出现差异。请注意以下可能的情况：

过早的事件： 如果在 Singular SDK 从应用会话中记录设备标识符之前收到事件请求，则该事件请求将被视为该未知设备的"首个会话"，Singular 会将该设备归因为 自然量归因
标识符不匹配： 如果 Singular SDK 记录了设备标识符，但它与 Server-to-Server 事件请求中指定的设备标识符不同，则该事件将被 错误归因

混合事件跟踪指南

从内部服务器发送事件

从您的内部服务器收集收入数据，以分析广告系列效果和 ROI。

要求：

捕获设备标识符： 从应用内的注册或登录事件中，捕获并传递设备标识符，并将该数据与用户 ID 一起存储在您的服务器上。由于用户的设备标识符可能会更改，请在用户生成应用会话时更新标识符。这可确保服务器端事件被归因到正确的设备
平台专属标识符： 服务器端事件是平台专属的，应仅使用与设备平台匹配的设备标识符发送（例如，iOS 设备使用 IDFA 或 IDFV，Android 设备使用 GAID）
实时更新： 使用 Singular 内部 BI 回传机制，将事件实时推送到您的内部端点，以便您可以更新服务器端的数据集。请参阅内部 BI 回传常见问题
实现细节： 有关详情，请查看 Server-to-Server 集成指南中的跟踪收入部分

从收入提供商发送事件

集成第三方收入提供商（如 RevenueCat 或 adapty），将购买和订阅收入发送到 Singular。

支持的提供商：

RevenueCat： 详情请参阅 RevenueCat 文档
adapty： 详情请参阅 adapty 文档
Superwall： 详情请参阅 Superwall 文档
Xsolla： 详情请参阅 Xsolla 文档

从 Segment 发送事件

通过在 Segment 中添加"Cloud-Mode"目标，使 Segment 能够与 Singular SDK 并行地向 Singular 发送事件。

有关详细的设置说明，请遵循实现指南 Singular-Segment 集成。

Flutter SDK - 跟踪应用内事件

跟踪应用内事件

标准事件和属性

了解事件类型

自定义事件限制

发送事件

Event 方法

EventWithArgs 方法

最佳实践

跟踪应用内收入

为什么要跟踪收入事件？

应用内购买集成

捕获 IAP 购买对象

InAppPurchase 方法

完整的 IAP 实现示例

手动收入跟踪

无购买验证的收入

CustomRevenue 方法

CustomRevenueWithAttributes 方法

CustomRevenueWithAllAttributes 方法

订阅收入

跟踪订阅

混合事件跟踪（高级）

混合事件跟踪指南

从内部服务器发送事件

从收入提供商发送事件

从 Segment 发送事件