跟踪应用程序内事件
注: 有关规划用户事件的详情,请参阅SDK 规划和先决条件指南中的应用程序是否会跟踪用户事件?
注:我们建议在应用程序中使用 Singular SDK 方法将所有应用程序内事件发送到 Singular 服务器。如果您计划从其他供应商或内部服务器发送事件到 Singular,请参阅下面的混合事件跟踪部分。
跟踪事件(非收入)
Singular可以收集应用程序内事件的相关数据,帮助分析营销活动的效果并衡量关键绩效指标。例如,您的企业可能希望收集有关用户登录、注册、教程完成或游戏应用中等级提升的数据。
发送到 Singular 的事件列表(附带属性)应由用户体验/营销/业务团队根据营销关键绩效指标编制。
有关规划用户事件的更多详情,请参阅SDK 规划和先决条件指南中的应用程序是否会跟踪用户事件?
在代码中,使用event或eventWithArgs方法向 Singular 发送标准事件。
注:对于标准事件,请使用 iOS SDK 标准事件和属性列表中的iOS 事件名称,如EVENT_SNG_LOGIN。
对于自定义事件,即企业希望测量的事件,如果与 Singular 的标准事件不匹配,可使用任意自定义名称(最多 32 个字符)。我们建议使用英文名称,以便与可能从 Singular 接收事件以进行优化的广告网络合作伙伴兼容。
事件 方法 | |
---|---|
说明 | 向 Singular 发送用户事件以进行跟踪。 |
签名 | (void)event:(NSString *)name |
使用示例 |
|
eventWithArgs 方法 | |
说明 | 将用户事件发送至 Singular 以供跟踪,并附带附加信息。 |
签名 | (void)eventWithArgs:(NSString *)name, ... |
使用示例 |
|
跟踪应用内收入
Singular 可捕获来自应用内购买(IAP)、订阅和自定义收入的收入事件,以衡量营销活动的绩效和广告支出回报率(ROAS)。收入数据可通过三个主要渠道获得:
- Singular 面板中的交互式报告
- 用于自定义分析的详细导出日志和 ETL 数据目的地
- 实时回传至外部平台
通过这种全面的收入跟踪,可以对营销支出和营销活动优化做出数据驱动型决策,同时还可以灵活地使用和分析数据。
要求
- 如果使用自定义收入事件名称,自定义收入事件名称仅限 32 个 ASCII 字符。对于非 ASCII 字符,转换为 UTF-8 后,限制为 32 字节。
- 事件属性名称和属性值限制为 500 个 ASCII 字符。
-
以三个字母的ISO 4217 货币代码形式传递货币:
USD, EUR, INR
最佳实践
- Singular 建议使用 Singular 的标准事件和属性命名约定传递事件。
- 如果使用自定义收入事件名称,则应以英文发送,以提高与广告网络回传的兼容性。
- 只有当收入金额大于或小于 0 时,才应向 Singular 发送收入事件。
非订阅应用内购买
重要:此方法不支持订阅跟踪!使用此方法进行非订阅应用内购买跟踪。
如果您的应用程序使用 App Store IAP 跟踪,建议使用iapComplete方法。
该方法会向 Singular 发送 IAP(苹果应用内购买)收入事件:
- 所有交易细节,Singular 将利用这些细节丰富报告内容。
- 交易收据,用于验证交易,分析或防止欺诈企图。
注意事项
- 使用 iapComplete 时,必须在事件中 包含 SKPaymentTransaction 对象。
- 任何以不同货币报告的收入都将自动转换为贵组织首选的货币,具体货币在您的 Singular 账户中设置。
iapComplete 方法
向 Singular 发送包含交易收据的收入事件。
签名
(void)iapComplete:(id)transaction
(void)iapComplete:(id)transaction withName:(NSString *)name;
使用示例
// *** Get the SKPaymentTransaction* transaction object ***
let transaction:SKPaymentTransaction = ...
// Send a transaction event to Singular without a custom event name
Singular.iapComplete(transaction)
// Send a transaction event to Singular with a custom event name
Singular.iapComplete(transaction, withName:"MyCustomRevenue")
// *** Get the SKPaymentTransaction* transaction object ***
SKPaymentTransaction* transaction = ...;
// Send a transaction event to Singular without a custom event name
[Singular iapComplete:transaction];
// Send a transaction event to Singular with a custom event name
[Singular iapComplete:transaction withName:@"MyCustomRevenue"];
订阅收入
跟踪订阅:
通过 Singular,您可以在应用程序中跟踪订阅和续订情况,深入了解用户行为和创收情况。查看我们的综合指南,了解如何使用 Singular SDK 实施订阅事件。[订阅事件技术实施指南]
无需购买验证的自定义收入
如果您的应用程序不支持应用商店应用内购买跟踪,建议使用 revenue 或 customRevenue 方法。这些方法不执行购买验证,也不应包含购买对象或收据。
通过revenue和customRevenue方法,您可以手动指定交易金额和货币,以及可选的其他详细信息,如产品序列号和数量等。customRevenue方法还允许您传递自定义事件名称。
注意:如果使用这些方法,Singular 不会验证购买交易。
收入方法
向 Singular 发送包含收入金额、货币和可选详细信息的收入事件。
签名
(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;
使用示例
// Revenue with no product details
Singular.revenue("USD", amount:1.99)
// Revenue with product details
Singular.revenue("EUR", amount:5.00,
productSKU:"SKU1928375",
productName:"Reservation Fee",
productCategory:"Fee",
productQuantity:1, productPrice:5.00)
// Send a Revenue Event with attributes 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)
// Revenue with no product details
[Singular revenue:@"USD" amount:1.99];
// Revenue with product details
[Singular revenue:@"EUR" amount:5.00 productSKU:@"SKU1928375"
productName:@"Reservation Fee"
productCategory:@"Fee"
productQuantity:1
productPrice:5.00];
// Send a Revenue Event with attributes 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];
自定义收入方法
通过指定事件名称、收入金额、货币代码和任何其他交易属性,向 Singular 发送自定义收入事件。Singular 会处理这些事件以跟踪应用程序内的收入。
签名
(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;
使用示例
// Revenue with a custom name and no product details
Singular.customRevenue("MyCustomRevenue", currency:"USD", amount:1.99)
// Revenue with a custom name and product details
Singular.customRevenue("MyCustomRevenue", currency:"EUR", amount:5.00,
productSKU:"SKU1928375",
productName:"Reservation Fee",
productCategory:"Fee",
productQuantity:1,
productPrice:5.00)
// Send a Custom Revenue Event with attributes 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)
// Revenue with a custom name and no product details
[Singular customRevenue:@"MyCustomRevenue" currency:@"USD" amount:1.99];
// Revenue with a custom name and product details
[Singular customRevenue:@"MyCustomRevenue" currency:@"EUR" amount:5.00
productSKU:@"SKU1928375"
productName:@"Reservation Fee"
productCategory:@"Fee"
productQuantity:1
productPrice:5.00];
// Send a Custom Revenue Event with attributes 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 框架进行应用程序内购买跟踪,建议使用customRevenue方法。customRevenue方法要求您在jsonRepresentation 中提供交易和产品对象。
StoreKit2 不支持购买验证
自定义收入方法
签名
+ (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 = ... // Assume this is a valid StoreKit2 transaction
let product = ... // Assume this is a valid StoreKit2 product
// Custom Revenue using __iap__ event name with transaction and product JSON representations
Singular.customRevenue(
transactionJsonRepresentation: transaction.jsonRepresentation,
productJsonRepresentation: product.jsonRepresentation )
// Custom Revenue with custom event name using transaction and product JSON representations
Singular.customRevenue(
"PaymentSuccess",
transactionJsonRepresentation: transaction.jsonRepresentation,
productJsonRepresentation: product.jsonRepresentation )
}
// Fetch transaction and product from StoreKit2
SKTransaction *transaction = ...; // Assume this is a valid StoreKit2 transaction
SKProduct *product = ...; // Assume this is a valid StoreKit2 product
// Convert transaction and product JSON representations to NSData
NSData *transactionData = [transaction.jsonRepresentation
dataUsingEncoding:NSUTF8StringEncoding];
NSData *productData = [product.jsonRepresentation
dataUsingEncoding:NSUTF8StringEncoding];
// Custom Revenue using transaction and product JSON representations
[Singular customRevenue:transactionData
productJsonRepresentation:productData];
// Custom Revenue with event name using transaction and product JSON representations
[Singular customRevenue:@"PaymentSuccess"
transactionJsonRepresentation:transactionData
productJsonRepresentation:productData];
混合事件跟踪(高级)
Singular 建议通过集成到应用程序中的 Singular SDK 发送所有事件和收入。不过,Singular 也可以从其他来源收集事件和收入。
任何非通过 Singular SDK 发送的事件都必须符合 Singular 的服务器到服务器事件文档要求,并提供匹配的设备标识符以正确归属事件。
重要:
如果服务器到服务器事件请求中使用的设备标识符在 Singular 中没有匹配的设备标识符,就会出现差异。请注意以下可能性:
- 如果事件请求是在 Singular SDK 从应用程序会话记录设备标识符之前收到的,那么该事件请求将被视为未知设备的 "第一次会话",Singular 将把该设备作为有机归属。
- 如果 Singular SDK 确实记录了设备标识符,但 Singular SDK 标识符与服务器到服务器事件请求中指定的设备标识符不同,那么事件将被错误归属。
混合事件跟踪指南
从内部服务器发送事件
Singular可以收集来自服务器的收入数据,帮助分析营销活动的表现和投资回报率。
要求
- 从应用程序内的注册或登录事件中捕获并传递设备标识符,并将此数据与服务器上的用户 ID 一起存储。由于用户的设备标识符可能会发生变化,因此请确保在用户生成应用程序会话时更新标识符。这将确保服务器端事件归属于正确的设备。
- 服务器端事件是平台特定的,只能使用与设备平台相匹配的设备标识符发送(如 iOS 设备的 IDFA 或 IDFV)。
- 您可以使用 Singular 内部 BI 回传机制将事件实时推送到内部端点,以便更新服务器端的数据集。请参阅内部 BI 回传常见问题。
- 查看服务器到服务器集成指南中的"跟踪收入 "部分,了解详情。
从收入提供商发送事件
第三方提供商(如RevenueCat或adapty)可以向 Singular 提供购买和订阅收入。
请点击以下链接了解如何启用这些合作伙伴。
从Segment发送事件
要使Segment与Singular SDK同时向Singular发送事件,您必须在Segment中添加一个"云模式 "目的地。请点击此处查看我们的指南。