Android SDK - 追踪应用内事件

关注
Avatar
Jared Ornstead
Updated

追踪应用内事件

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

标准事件和属性

使用标准事件

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

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

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

发送事件

事件实现指南

使用 eventJSON 或 event 方法向 Singular 发送事件（我们建议使用 eventJSON 以提高可读性）。

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

自定义事件限制：

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

eventJSON 方法

使用 JSONObject 格式报告带有附加信息的用户事件，以获得结构化数据。

方法签名： 

Singular.eventJSON(String name, JSONObject args)

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

使用示例

Kotlin Java 
// Example 1: Standard event with recommended attributes
val att = JSONObject().apply {
    put(Attributes.sngAttrContent.toString(), "Telugu")
    put(Attributes.sngAttrContentId.toString(), 32)
    put(Attributes.sngAttrContentType.toString(), "video")
    put(Attributes.sngAttrSuccess.toString(), 75)
}
Singular.eventJSON(Events.sngTutorialComplete.toString(), att)

// Example 2: Custom event with custom attributes
val att = JSONObject().apply {
    put("Points", 500)
    put("score", 650)
}
Singular.eventJSON("Bonus Points Earned", att)

event 方法

使用可变参数报告带有或不带有附加信息的用户事件。

方法签名： 

Singular.event(String eventName)
Singular.event(String eventName, Object... args)

注意： args 参数接受一个或多个键值对。键必须是字符串，值可以是 JSONObject 值所允许的任何类型（JSONObject、JSONArray、String、Boolean、Integer、Long、Double 或 NULL）。 args 列表必须包含偶数个元素，否则事件将被拒绝。

使用示例

Kotlin Java 
// Example 1: Standard event without attributes
Singular.event(Events.sngSubscribe.toString())

// Example 2: Standard event with recommended attributes
Singular.event(Events.sngTutorialComplete.toString(),
    Attributes.sngAttrContent.toString(), "Telugu",
    Attributes.sngAttrContentId.toString(), "32",
    Attributes.sngAttrContentType.toString(), "video",
    Attributes.sngAttrSuccess.toString(), "yes"
)

// Example 3: Custom event without attributes
Singular.event("SignUp")

// Example 4: Custom event with custom attribute
Singular.event("Bonus Points Earned", "Points", 500)

追踪应用内收入

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

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

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

收入事件限制：

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

最佳实践

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

非订阅应用内购买

Purchase 对象集成

将 Google Billing Library 中的 Purchase 对象传递给 revenue 或 customRevenue 方法，以获得更丰富的报告和交易验证。

优势：

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

注意：

  • 自定义事件名称： customRevenue 方法接受自定义事件名称，用于在报告中按事件类型细分收入
  • 货币转换： 不同货币的收入会自动转换为您组织的首选货币

使用 Purchase 的 revenue 方法

发送带有 Purchase 对象的收入事件，以实现自动验证和丰富的数据。

方法签名： 

Singular.revenue(String currency, double amount, Object purchase)

使用示例

Kotlin Java 
Singular.revenue("USD", 5.50, purchase)

使用 Purchase 的 customRevenue 方法

发送带有自定义名称和 Purchase 对象的收入事件，以进行分类收入追踪。

方法签名： 

Singular.customRevenue(String eventName, String currency, double amount, Object purchase)

使用示例

Kotlin Java 
Singular.customRevenue("MyCustomRevenue", "USD", 5.50, purchase)

订阅收入

订阅事件实现

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

实现指南： 请查看全面的 订阅事件技术实现指南 ，了解使用 Singular SDK 追踪订阅的详细说明。

无 Purchase 验证的自定义收入

手动收入追踪

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

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

无 Purchase 的 revenue 方法

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

方法签名： 

Singular.revenue(String currency, double amount)
Singular.revenue(String currency, double amount, String productSKU, String productName, String productCategory, int productQuantity, double productPrice)
Singular.revenue(String currency, double amount, Map<String, Object> attributes)

使用示例

Kotlin Java 
// Without product details
Singular.revenue("USD", 5.50)

// With product details
Singular.revenue("EUR", 5.00, "SKU1928375", "Reservation Fee", "Fee", 1, 5.00)

// With product details in an attribute map
val attributes = mutableMapOf<String, Any>().apply {
    put("product_id", "com.app.premium")
    put("transaction_id", "T12345")
    put("quantity", 1)
    put("is_trial", false)
}
Singular.revenue("USD", 9.99, attributes)

无 Purchase 的 customRevenue 方法

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

方法签名： 

Singular.customRevenue(String eventName, String currency, double amount)
Singular.customRevenue(String eventName, String currency, double amount, String productSKU, String productName, String productCategory, int productQuantity, double productPrice)
Singular.customRevenue(String eventName, String currency, double amount, Map<String, Object> attributes)

使用示例

Kotlin Java 
// Without product details
Singular.customRevenue("MyCustomRevenue", "USD", 5.50)

// With product details
Singular.customRevenue("MyCustomRevenue", "EUR", 5.00, "SKU1928375", "Reservation Fee", "Fee", 1, 5.00)

// With product details in an attribute map
val attributes = mutableMapOf<String, Any>().apply {
    put("product_id", "com.app.premium")
    put("transaction_id", "T12345")
    put("quantity", 1)
    put("is_trial", false)
}
Singular.customRevenue("MyCustomRevenue", "USD", 9.99, attributes)

混合事件追踪（高级）

为实现最佳归因，请通过集成到您应用中的 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。

支持的提供商：

从 Segment 发送事件

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

请按照实现指南 Singular-Segment 集成 获取详细的设置说明。