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

关注
Avatar
Jared Ornstead
Updated
文档

跟踪应用程序内事件

注： 有关规划用户事件的详情，请参阅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
使用示例
SwiftObjective-C 
// Using Standard Event


Singular.event(EVENT_SNG_LOGIN)

// Using Custom Event


Singular.event("signup")
eventWithArgs 方法
说明 将用户事件发送至 Singular 以供跟踪，并附带附加信息。
签名 (void)eventWithArgs:(NSString *)name, ...
使用示例
SwiftObjective-C 
//Using Standard Event
var dic: [AnyHashable : Any] = [:]
dic[ATTRIBUTE_SNG_ATTR_CONTENT_TYPE] = "PrivacyController"
dic[ATTRIBUTE_SNG_ATTR_CONTENT_ID] = "0"
dic[ATTRIBUTE_SNG_ATTR_CONTENT] = "GDPR and CCPA Opt-Out Options"
Singular.event(EVENT_SNG_CONTENT_VIEW, withArgs: dic)

//Using Custom Event
var bonusdata: [AnyHashable: Any] = [ "level": 10, "points": 500 ]
Singular.event("Bonus Points Earned", withArgs: bonusdata)

跟踪应用内收入

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;

使用示例

SwiftObjective-C 
// *** 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")

订阅收入

跟踪订阅：

通过 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;

使用示例

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

自定义收入方法

通过指定事件名称、收入金额、货币代码和任何其他交易属性，向 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;

使用示例

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

支持 StoreKit2

如果您的应用程序使用StoreKit2 框架进行应用程序内购买跟踪，建议使用customRevenue方法。customRevenue方法要求您在jsonRepresentation 中提供交易和产品对象。

StoreKit2 不支持购买验证

自定义收入方法

签名

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

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

使用示例

SwiftObjective-C 
// 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 )
}

混合事件跟踪（高级）

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中添加一个"云模式 "目的地。请点击此处查看我们的指南。