文档

跟踪应用程序内事件

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

标准事件和属性

了解事件类型

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

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

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

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

自定义事件限制

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

自定义事件限制：

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

发送事件

事件方法

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

// Track a simple custom event
cordova.plugins.SingularCordovaSdk.event('SignUp');

// Track a standard event
cordova.plugins.SingularCordovaSdk.event('sngLogin');

方法签名：

event(eventName: string): void

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

EventWithArgs 方法

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

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

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

方法特征：

eventWithArgs(eventName: string, args: Object): void

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

最佳实践

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

跟踪应用内收入

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

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

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

为什么要跟踪收入事件？

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

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

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

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

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

应用内购买集成

捕获 IAP 购买对象

使用 Cordova IAP 插件从平台商店检索包含完整交易详细信息的购买对象。

iOS：使用cordova-plugin-purchase或类似插件访问 StoreKit 购买详情
安卓：使用cordova-plugin-purchase或类似插件获取 Google Play Billing 购买详情

SingularIAP 构造函数

创建一个应用内购买对象，用于通过特定平台的收据验证和欺诈预防来跟踪收入。

构造函数签名：

function SingularIAP(product: Object): SingularIAP

有关完整的构造函数参考，请参阅SingularIAP 构造函数参考。

完整 IAP 实现示例

实现一个完整的购买监听器，该监听器可捕获 IAP 事件，并通过特定平台的购买对象将其发送至 Singular。

// Import Singular SDK and SingularIAP constructor
var Singular = cordova.plugins.SingularCordovaSdk;
var SingularIAP = cordova.require('singular-cordova-sdk.SingularIAP');

// iOS App Store purchase example
function handleiOSPurchase(purchase) {
  // Create iOS product object
  var iosProduct = {
    currency: 'USD',
    price: 4.99,
    id: 'com.app.premiumgems',
    transaction: {
      type: 'ios-appstore',
      appStoreReceipt: purchase.receipt, // Base64 receipt from StoreKit
      id: purchase.transactionId // Transaction identifier
    }
  };

  // Create SingularIAP object
  var iosIAP = new SingularIAP(iosProduct);

  // Track the purchase with Singular
  // The SingularIAP object is passed as additional args
  cordova.plugins.SingularCordovaSdk.eventWithArgs('iap_purchase', iosIAP);
}

// Android Play Store purchase example
function handleAndroidPurchase(purchase) {
  // Create Android product object
  var androidProduct = {
    currency: 'USD',
    price: 4.99,
    id: 'com.app.premiumgems',
    transaction: {
      type: 'android-playstore',
      receipt: purchase.receipt, // JSON receipt from Google Play
      signature: purchase.signature // Signature from Google Play
    }
  };

  // Create SingularIAP object
  var androidIAP = new SingularIAP(androidProduct);

  // Track the purchase with Singular
  cordova.plugins.SingularCordovaSdk.eventWithArgs('iap_purchase', androidIAP);
}

// Example integration with cordova-plugin-purchase
document.addEventListener('deviceready', function() {
  // Initialize the store
  store.register({
    id: 'com.app.premiumgems',
    type: store.CONSUMABLE
  });

  // Handle purchase approved
  store.when('com.app.premiumgems').approved(function(product) {
    // Determine platform and handle accordingly
    if (device.platform === 'iOS') {
      handleiOSPurchase(product.transaction);
    } else if (device.platform === 'Android') {
      handleAndroidPurchase(product.transaction);
    }

    // Finish the transaction
    product.finish();
  });

  // Refresh the store
  store.refresh();
});

要点：

SingularIAP 构造函数可格式化 iOS 和 Android 平台的购买数据。
将生成的 IAP 对象作为args 参数传递到eventWithArgs()
IAP 对象包括用于防止欺诈的收据验证数据
Singular 自动提取收入、货币和产品详细信息

手动收入跟踪

无需购买验证的收入

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

重要：在发送收入事件时，如果没有有效的购买对象，Singular 不会验证交易。我们强烈建议尽可能使用上述SingularIAP 构造函数。

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

收入方法

跟踪具有指定货币和金额的简单收入事件。

// Track revenue without product details
cordova.plugins.SingularCordovaSdk.revenue('USD', 4.99);

方法签名：

revenue(currency: string, amount: number): void

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

RevenueWithArgs 方法

跟踪带有指定货币、金额和附加自定义属性的收入事件。

// Track revenue with attributes
cordova.plugins.SingularCordovaSdk.revenueWithArgs('USD', 9.98, {
  productSKU: 'coin_package_abc123',
  productName: 'Coin Pack 10',
  productCategory: 'Bundles',
  productQuantity: 2,
  productPrice: 4.99,
  transaction_id: 'T12345'
});

方法签名：

revenueWithArgs(currency: string, amount: number, args: Object): void

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

自定义收入方法

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

// Track custom revenue event
cordova.plugins.SingularCordovaSdk.customRevenue('PremiumUpgrade', 'USD', 9.99);

方法签名：

customRevenue(eventName: string, currency: string, amount: number): void

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

CustomRevenueWithArgs 方法

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

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

方法签名：

customRevenueWithArgs(eventName: string, currency: string, amount: number, args: Object): void

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

订阅收入

跟踪订阅

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实施指南。

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

跟踪应用程序内事件

标准事件和属性

了解事件类型

自定义事件限制

发送事件

事件方法

EventWithArgs 方法

最佳实践

跟踪应用内收入

为什么要跟踪收入事件？

应用内购买集成

捕获 IAP 购买对象

SingularIAP 构造函数

完整 IAP 实现示例

手动收入跟踪

无需购买验证的收入

收入方法

RevenueWithArgs 方法

自定义收入方法

CustomRevenueWithArgs 方法

订阅收入

跟踪订阅

混合事件跟踪（高级）

混合事件跟踪指南

从内部服务器发送事件

从收入提供商发送事件

从Segment发送事件