文档

跟踪应用程序内事件

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

标准事件和属性

使用标准事件

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

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

每个事件都支持各种属性。有关实施详情，请参阅每个事件的推荐标准属性。

发送事件

事件实施指南

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

标准事件：使用标准事件列表中事件的 iOS 名称，如EVENT_SNG_LOGIN。
自定义事件：对于不符合标准事件的应用程序特有事件，可使用任何符合字符限制的描述性字符串

自定义事件限制：

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

事件方法

报告用户事件，不含额外信息，适用于简单的跟踪场景。

方法签名：

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

使用示例

// 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 面板中查看收入指标
导出日志：访问详细的 ETL 数据，进行自定义分析
实时回传：向外部平台发送收入事件

收入事件限制：

事件名称：自定义收入事件名称限制为 32 个 ASCII 字符（或转换为 UTF-8 后 32 个字节的非 ASCII 字符
属性：事件属性名称和值限制为 500 ASCII 字符
货币代码：必须使用大写字母，并遵循三个字母的ISO 4217 标准（如美元、欧元、印度卢比

最佳实践

标准命名：使用 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 方法。

收入方法

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

方法签名：

+ (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];

自定义收入方法

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

方法签名：

+ (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 框架的应用程序，请使用带有交易和产品 JSON 表示的customRevenue方法。

重要：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 记录的设备标识符与服务器到服务器请求中的设备标识符不同，事件将被错误归属

混合事件跟踪指南

从内部服务器发送事件

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

要求：

捕获设备标识符：在应用内注册或登录事件中，捕获并传递设备标识符，然后将此数据与用户 ID 一起存储在服务器上。当用户生成新的应用程序会话时更新标识符，以确保正确的归因
平台特定标识符：发送带有与平台匹配的设备标识符的服务器端事件（如 iOS 设备的 IDFA 或 IDFV）
实时更新：使用 Singular 内部商业智能回传机制将事件实时推送到您的终端。请参阅内部 BI 回传常见问题
实施细节：查看服务器到服务器集成指南中的"跟踪收入 "部分

从收入提供商发送事件

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

支持的供应商：

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

从Segment发送事件

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

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

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

跟踪应用程序内事件

标准事件和属性

使用标准事件

发送事件

事件实施指南

事件方法

使用示例

eventWithArgs 方法

使用示例

跟踪应用程序内收入

最佳实践

非订阅应用内购买

SKPaymentTransaction 集成

iapComplete 方法

使用示例

订阅收入

订阅事件实施

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

手动收入跟踪

收入方法

使用示例

自定义收入方法

使用示例

StoreKit2 支持

StoreKit2 收入跟踪

使用示例

混合事件跟踪（高级）

混合事件跟踪指南

从内部服务器发送事件

从收入提供商发送事件

从Segment发送事件