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

关注
Avatar
Jared Ornstead
Updated
文档 Android SDK - 事件和收入跟踪

跟踪应用程序内事件

跟踪应用内事件以分析营销活动绩效并衡量关键绩效指标（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 值的类型。

使用示例

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

事件 方法

使用变量参数报告有或无附加信息的用户事件。

方法签名： 

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

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

使用示例

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

收入事件限制：

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

最佳实践

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

非订阅应用内购买

购买对象集成

将购买对象从 Google Billing Library 传递到revenue 或customRevenue 方法，以丰富报告和交易验证。

优点

  • 丰富的数据：单一接收完整的交易详细信息，以生成全面的报告
  • 防止欺诈：交易收据可用于验证，以打击应用程序内的欺诈行为

备注

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

带购买的收入方法

与购买对象一起发送收入事件，以便自动验证和丰富数据。

方法签名： 

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

使用示例

KotlinJava 
Singular.revenue("USD", 5.50, purchase)

自定义收入方法

发送带有自定义名称和购买对象的收入事件，用于分类收入跟踪。

方法签名： 

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

使用示例

KotlinJava 
Singular.customRevenue("MyCustomRevenue", "USD", 5.50, purchase)

订阅收入

订阅事件实施

跟踪订阅购买和续订情况，深入了解用户行为和经常性收入的产生。

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

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

手动收入跟踪

通过传递货币、金额和可选产品详细信息来跟踪收入，而无需购买对象。请注意，此方法不提供用于验证的交易收据。

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

无购买的收入方法

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

方法签名： 

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)

使用示例

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

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)

使用示例

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

混合事件跟踪指南

从内部服务器发送事件

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

要求：

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

从收入提供商发送事件

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

支持的供应商：

从Segment发送事件

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

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