应用内事件追踪

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

标准事件和归因

使用标准事件

Singular 支持广告网络识别的标准事件 ,用于报告和优化。请尽可能使用标准事件名称,以实现自动识别和简化配置。

您的 UA、市场或业务团队应根据组织的市场 KPI 编制事件清单。规划时请参考指南如何追踪应用内事件:Singular Attribution 客户指南。

每个事件都支持多种归因。有关实施细节,请参阅每个事件推荐的标准归因。

发送事件

事件实施指南

使用 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 将静默丢弃该事件。请检查日志以发现问题。

使用示例

// Example 1: Standard event
Singular.event(EVENT_SNG_LOGIN)

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

// 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 中允许的任何类型。

使用示例

// 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)

// Example 1: Standard event with recommended attributes
NSMutableDictionary *dic = [[NSMutableDictionary alloc] init];
[dic setValue:@"video" forKey:ATTRIBUTE_SNG_ATTR_CONTENT_TYPE];
[dic setValue:@"32" forKey:ATTRIBUTE_SNG_ATTR_CONTENT_ID];
[dic setValue:@"Telugu" forKey:ATTRIBUTE_SNG_ATTR_CONTENT];
[dic setValue:@"yes" forKey:ATTRIBUTE_SNG_ATTR_SUCCESS];

[Singular event:EVENT_SNG_TUTORIAL_COMPLETE withArgs:dic];

// Example 2: Custom event with custom attributes
NSMutableDictionary *bonusData = [[NSMutableDictionary alloc] init];
[bonusData setValue:@10 forKey:@"level"];
[bonusData setValue:@500 forKey:@"points"];

[Singular event:@"Bonus Points Earned" withArgs:bonusData];

应用内收入追踪

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

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

交互式报告: 在 Singular 仪表盘中查看收入指标
Export Logs: 访问详细的 ETL 数据以进行自定义分析
实时回调: 将收入事件发送到外部平台

收入事件限制:

事件名称: 自定义收入事件名称限制为 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;

使用示例

// 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")

// Get the SKPaymentTransaction object
SKPaymentTransaction *transaction = ...;

// 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;

使用示例

// 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)

// 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
NSMutableDictionary *dic = [[NSMutableDictionary alloc] init];
[dic setValue:@"100% Organic Cotton Mixed Plaid Flannel Shirt"
       forKey:ATTRIBUTE_SNG_ATTR_ITEM_DESCRIPTION];
[dic setValue:@"$69.95" forKey:ATTRIBUTE_SNG_ATTR_ITEM_PRICE];
[dic setValue:@"5 Star" forKey:ATTRIBUTE_SNG_ATTR_RATING];
[dic setValue:@"Flannel Shirt" forKey:ATTRIBUTE_SNG_ATTR_SEARCH_STRING];

[Singular revenue:@"USD" amount:19.99 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;

使用示例

// 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)

// 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
NSMutableDictionary *dic = [[NSMutableDictionary alloc] init];
[dic setValue:@"100% Organic Cotton Mixed Plaid Flannel Shirt"
       forKey:ATTRIBUTE_SNG_ATTR_ITEM_DESCRIPTION];
[dic setValue:@"$69.95" forKey:ATTRIBUTE_SNG_ATTR_ITEM_PRICE];
[dic setValue:@"5 Star" forKey:ATTRIBUTE_SNG_ATTR_RATING];
[dic setValue:@"Flannel Shirt" forKey:ATTRIBUTE_SNG_ATTR_SEARCH_STRING];

[Singular customRevenue:@"MyCustomRevenue"
               currency:@"USD"
                 amount:44.99
         withAttributes:dic];

StoreKit2 支持

StoreKit2 收入追踪

对于使用 StoreKit2 框架的应用,请使用 customRevenue 方法,并传入交易和产品的 JSON 表示。

重要: StoreKit2 不支持购买验证。这些方法要求交易和产品对象采用 jsonRepresentation 格式。

方法签名:

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

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

使用示例

// 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)

// Fetch transaction and product from StoreKit2
SKTransaction *transaction = ...;  // Valid StoreKit2 transaction
SKProduct *product = ...;          // Valid StoreKit2 product

// Convert JSON representations to NSData
NSData *transactionData = [transaction.jsonRepresentation
    dataUsingEncoding:NSUTF8StringEncoding];
NSData *productData = [product.jsonRepresentation
    dataUsingEncoding:NSUTF8StringEncoding];

// Custom Revenue with default __iap__ event name
[Singular customRevenue:transactionData
    productJsonRepresentation:productData];

// Custom Revenue with custom event name
[Singular customRevenue:@"PaymentSuccess"
    transactionJsonRepresentation:transactionData
    productJsonRepresentation:productData];

混合事件追踪(高级)

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

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

重要:

当服务器到服务器请求中的设备标识符与 Singular SDK 记录的标识符不一致时,会出现差异:

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

混合事件追踪指南

从内部服务器发送事件

从您的内部服务器收集收入数据,以分析广告系列表现和 ROI。

要求:

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

从收入提供商发送事件

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

支持的提供商:

RevenueCat: 详情请参见 RevenueCat 文档
adapty: 详情请参见 adapty 文档

从 Segment 发送事件

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

有关详细的设置说明,请参阅实施指南 Singular-Segment 集成 。

iOS SDK - 应用内事件追踪

应用内事件追踪

标准事件和归因

使用标准事件

发送事件

事件实施指南

event 方法

使用示例

eventWithArgs 方法

使用示例

应用内收入追踪

最佳实践

非订阅类应用内购买

SKPaymentTransaction 集成

iapComplete 方法

使用示例

订阅收入

订阅事件实施

无购买验证的自定义收入

手动收入追踪

revenue 方法

使用示例

customRevenue 方法

使用示例

StoreKit2 支持

StoreKit2 收入追踪

使用示例

混合事件追踪(高级)

混合事件追踪指南

从内部服务器发送事件

从收入提供商发送事件

从 Segment 发送事件