追踪应用内事件

关注
Avatar
Jared Ornstead
Updated

追踪应用内事件

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

标准事件和属性

使用标准事件

Singular 支持 标准事件 ，这些事件会被广告渠道识别，用于报告和优化。请尽可能使用标准事件名称，以实现自动识别并简化设置。

您的用户获取（UA）、营销或业务团队应根据组织的营销 KPI 编制事件列表。规划时请参考指南 如何追踪应用内事件：Singular 归因客户指南 。

每个事件都支持多种属性。有关实现细节，请参阅 每个事件的推荐标准属性 。

发送事件

事件实现指南

使用 event 或 eventWithArgs 方法向 Singular 发送事件，以追踪用户操作和行为。

  • 标准事件： 使用标准事件列表中的 事件的 iOS 名称 ，例如 EVENT_SNG_LOGIN
  • 自定义事件： 对于应用特有且与标准事件不匹配的事件，请使用任何符合字符限制的描述性字符串

自定义事件限制：

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

event 方法

在简单的追踪场景中，报告不含附加信息的用户事件。

方法签名： 

+ (void)event:(NSString *)name;

+event: 返回 void — 在调用处没有成功/失败信号。当事件名称为 nil 或为空，或者尚未调用 +start: 时，SDK 会静默丢弃该事件。请检查日志以排查问题。

使用示例

Swift Objective-C 
// Example 1: Standard event
Singular.event(EVENT_SNG_LOGIN)

// Example 2: Custom event
Singular.event("signup")

eventWithArgs 方法

使用字典格式报告包含附加信息的用户事件，以传递结构化数据。

方法签名： 

+ (void)event:(NSString *)name withArgs:(NSDictionary *)args;

注意： args 参数是一个 NSDictionary，包含一个或多个键值对。键必须是字符串，值可以是 NSDictionary 中允许的任何类型。

使用示例

Swift Objective-C 
// Example 1: Standard event with recommended attributes
var dic: [AnyHashable: Any] = [:]
dic[ATTRIBUTE_SNG_ATTR_CONTENT_TYPE] = "video"
dic[ATTRIBUTE_SNG_ATTR_CONTENT_ID] = "32"
dic[ATTRIBUTE_SNG_ATTR_CONTENT] = "Telugu"
dic[ATTRIBUTE_SNG_ATTR_SUCCESS] = "yes"

Singular.event(EVENT_SNG_TUTORIAL_COMPLETE, withArgs: dic)

// Example 2: Custom event with custom attributes
var bonusData: [AnyHashable: Any] = [
    "level": 10,
    "points": 500
]
Singular.event("Bonus Points Earned", withArgs: bonusData)

追踪应用内收入

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

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

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

收入事件限制：

  • 事件名称： 自定义收入事件名称限制为 32 个 ASCII 字符（非 ASCII 字符转换为 UTF-8 后为 32 字节）
  • 属性： 事件属性名称和值限制为 500 个 ASCII 字符
  • 货币代码： 必须全部大写，并遵循三字母的 ISO 4217 标准 （例如 USD、EUR、INR）

最佳实践

  • 标准命名： 使用 Singular 的 标准事件和属性命名约定
  • 语言： 以英文发送自定义收入事件名称，以提高广告渠道回传的兼容性
  • 非零金额： 仅在金额大于或小于 0 时发送收入事件

非订阅应用内购买

SKPaymentTransaction 集成

将 StoreKit 中的 SKPaymentTransaction 对象传递给 iapComplete 方法，以获得更丰富的报告和交易验证。

优势：

  • 丰富的数据： Singular 接收完整的交易详情，以生成全面的报告
  • 欺诈防范： 交易收据可支持验证，以打击应用内欺诈

注意：

  • 必需对象： iapComplete 方法需要 SKPaymentTransaction 对象
  • 货币转换： 不同货币的收入会自动转换为您组织的首选货币
  • 自定义事件名称： 使用 withName 参数在报告中按事件类型对收入进行分类

iapComplete 方法

发送包含 SKPaymentTransaction 对象的收入事件，以实现自动验证和丰富的数据。

方法签名： 

+ (void)iapComplete:(id)transaction;
+ (void)iapComplete:(id)transaction withName:(NSString *)name;

使用示例

Swift Objective-C 
// Get the SKPaymentTransaction object
let transaction: SKPaymentTransaction = ...

// Send transaction without custom event name
Singular.iapComplete(transaction)

// Send transaction with custom event name
Singular.iapComplete(transaction, withName: "MyCustomRevenue")

订阅收入

订阅事件实现

追踪订阅购买和续订，以深入了解用户行为和经常性收入的产生情况。

实现指南： 请查阅完整的 订阅事件技术实现指南 ，以获取使用 Singular SDK 追踪订阅的详细说明。

无需购买验证的自定义收入

手动收入追踪

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

重要： 使用这些方法时，Singular 无法验证交易。我们强烈建议尽可能使用上述 SKPaymentTransaction 方法。

revenue 方法

发送包含货币、金额和可选产品详情的收入事件。

方法签名： 

+ (void)revenue:(NSString *)currency amount:(double)amount;

+ (void)revenue:(NSString *)currency
         amount:(double)amount
     productSKU:(NSString *)productSKU
    productName:(NSString *)productName
productCategory:(NSString *)productCategory
productQuantity:(int)productQuantity
   productPrice:(double)productPrice;

+ (void)revenue:(NSString *)currency
         amount:(double)amount
 withAttributes:(NSDictionary *)attributes;

使用示例

Swift Objective-C 
// Without product details
Singular.revenue("USD", amount: 1.99)

// With product details
Singular.revenue("EUR",
    amount: 5.00,
    productSKU: "SKU1928375",
    productName: "Reservation Fee",
    productCategory: "Fee",
    productQuantity: 1,
    productPrice: 5.00)

// With product details in a dictionary
var dic: [AnyHashable: Any] = [:]
dic[ATTRIBUTE_SNG_ATTR_ITEM_DESCRIPTION] = "100% Organic Cotton Mixed Plaid Flannel Shirt"
dic[ATTRIBUTE_SNG_ATTR_ITEM_PRICE] = "$69.95"
dic[ATTRIBUTE_SNG_ATTR_RATING] = "5 Star"
dic[ATTRIBUTE_SNG_ATTR_SEARCH_STRING] = "Flannel Shirt"

Singular.revenue("USD", amount: 19.95, withAttributes: dic)

customRevenue 方法

发送包含指定事件名称、货币、金额和可选交易属性的自定义收入事件。

方法签名： 

+ (void)customRevenue:(NSString *)eventName
             currency:(NSString *)currency
               amount:(double)amount;

+ (void)customRevenue:(NSString *)eventName
             currency:(NSString *)currency
               amount:(double)amount
           productSKU:(NSString *)productSKU
          productName:(NSString *)productName
      productCategory:(NSString *)productCategory
      productQuantity:(int)productQuantity
         productPrice:(double)productPrice;

+ (void)customRevenue:(NSString *)eventName
             currency:(NSString *)currency
               amount:(double)amount
       withAttributes:(NSDictionary *)attributes;

使用示例

Swift Objective-C 
// Without product details
Singular.customRevenue("MyCustomRevenue", currency: "USD", amount: 1.99)

// With product details
Singular.customRevenue("MyCustomRevenue",
    currency: "EUR",
    amount: 5.00,
    productSKU: "SKU1928375",
    productName: "Reservation Fee",
    productCategory: "Fee",
    productQuantity: 1,
    productPrice: 5.00)

// With product details in a dictionary
var dic: [AnyHashable: Any] = [:]
dic[ATTRIBUTE_SNG_ATTR_ITEM_DESCRIPTION] = "100% Organic Cotton Mixed Plaid Flannel Shirt"
dic[ATTRIBUTE_SNG_ATTR_ITEM_PRICE] = "$69.95"
dic[ATTRIBUTE_SNG_ATTR_RATING] = "5 Star"
dic[ATTRIBUTE_SNG_ATTR_SEARCH_STRING] = "Flannel Shirt"

Singular.customRevenue("CustomRevenueWithArgsDic",
    currency: "USD",
    amount: 44.99,
    withAttributes: dic)

StoreKit2 支持

StoreKit2 收入追踪

对于使用 StoreKit2 框架的应用，请结合交易和产品的 JSON 表示形式使用 customRevenue 方法。

现已在 SDK 12.13+ 版本中支持 Storekit2 验证。这些方法要求交易和产品对象采用 jsonRepresentation 格式。

方法签名： 

+ (void)customRevenue:(NSData *)transactionJsonRepresentation
productJsonRepresentation:(NSData *)productJsonRepresentation;

+ (void)customRevenue:(NSString *)eventName
transactionJsonRepresentation:(NSData *)transactionJsonRepresentation
productJsonRepresentation:(NSData *)productJsonRepresentation;

使用示例

Swift Objective-C 
// Fetch transaction and product from StoreKit2
let transaction = ... // Valid StoreKit2 transaction
let product = ... // Valid StoreKit2 product

// Custom Revenue with default __iap__ event name
Singular.customRevenue(
    transactionJsonRepresentation: transaction.jsonRepresentation,
    productJsonRepresentation: product.jsonRepresentation)

// Custom Revenue with custom event name
Singular.customRevenue(
    "PaymentSuccess",
    transactionJsonRepresentation: transaction.jsonRepresentation,
    productJsonRepresentation: product.jsonRepresentation)

混合事件追踪（高级）

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

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

重要：

当服务器到服务器请求中的设备标识符与 Singular SDK 记录的标识符不匹配时，会出现差异：

  • 过早事件： 如果事件在 Singular SDK 记录设备标识符之前到达，该事件将成为某个未知设备的"首次会话"，从而导致自然量归因
  • 标识符不匹配： 如果 Singular SDK 记录的设备标识符与服务器到服务器请求中的标识符不同，该事件将被错误归因

混合事件追踪指南

从内部服务器发送事件

从您的内部服务器收集收入数据，以分析广告系列效果和投资回报率（ROI）。

要求：

  • 捕获设备标识符： 在应用内注册或登录事件期间，捕获并传递设备标识符，然后将此数据与用户 ID 一起存储在您的服务器上。当用户生成新的应用会话时，请更新标识符以确保正确归因
  • 平台特定标识符： 发送服务器端事件时，请使用与平台匹配的设备标识符（例如，iOS 设备使用 IDFA 或 IDFV）
  • 实时更新： 使用 Singular Internal BI 回传机制将事件实时推送到您的端点。请参阅 Internal BI Postback FAQ
  • 实现细节： 请查阅服务器到服务器集成指南中的 "Tracking Revenue" 部分

从收入提供商发送事件

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

支持的提供商：

从 Segment 发送事件

通过在 Segment 中添加"云模式（Cloud-Mode）"目标，让 Segment 在 Singular SDK 之外并行地将事件发送到 Singular。

请按照实现指南 Singular-Segment 集成 进行详细的设置。