Google Analytics 4 (GA4) 归因回传集成设置

关注
Avatar
Ghani Yusuf
Updated
文件

概述

Singular作为第三方分析合作伙伴，支持与Google Analytics 4（GA4）的集成。
本指南说明如何通过 Singular 为您的移动应用配置 GA4 测量，并确保正确传递所需参数。

Singular会自动将营销活动归因数据转发至GA4，但需在Singular界面和SDK中配置特定凭证及标识符。

说明：Singular将归因数据转发至GA4用于测量和报告。漏斗分析、用户行为分析等产品分析仍需直接在GA4或Firebase中处理。

从 Singular 发送到 GA4 的参数

Singular自动转发以下参数至Google Analytics 4：

  • 活动名称

  • 活动ID

  • 来源

  • 媒介

  • 时间戳

说明：这些参数将根据Singular归因数据自动填充，无需额外配置SDK。

在Singular合作伙伴配置界面中必需的配置

为启用GA4测量功能，必须在Singular控制面板中直接配置以下值：

Screenshot of Singular GA4 partner configuration

1. API密钥（api_secret ）

GA4测量协议API密钥。

获取路径：

GA4 Admin → Data Streams → Select your stream → Measurement Protocol → Create API Secret

重要提示：Singular需通过测量协议向GA4发送事件时必须提供此密钥。若未配置该值，GA4事件将无法被记录。

2. Firebase 应用 ID（firebase_app_id ）

与您的移动应用关联的 Firebase 应用 ID。

获取位置：

Firebase Console → Project Settings → General → Your Apps → App ID
Screenshot of Firebase App ID location

注意：确保在Singular中配置的firebase_app_id 与生产环境构建中使用的Firebase应用完全一致。不匹配将导致GA4无法将事件关联至您的应用。

Singular SDK 所需配置

3. 应用实例 ID（app_instance_id ）

app_instance_id 是Firebase应用特定安装版本的唯一标识符。

要求：

  • 从 Firebase SDK 获取该值

  • 通过本指南所述的GLOBAL_PROPERTIES传递至 Singular SDK

  • 使用精确属性名称：app_instance_id

注意： app_instance_id 必须在初始化Singular SDK之前设置。初始化后设置此值可能导致GA4事件丢失或归因错误。

SDK 实现示例（Android – Kotlin）

使用全局属性在应用生命周期中追踪应用级和用户特定标识符。

// Initialize the Singular SDK with app-level global properties val config = SingularConfig("SDK_KEY", "SDK_SECRET") .withGlobalProperty("app_instance_id", firebaseAppInstanceId, true) Singular.init(applicationContext, config)

// Set a third-party identifier on user login
fun onUserLogin(thirdPartyUserId: String) {
val success = Singular.setGlobalProperty(
"third_party_identifier",
thirdPartyUserId,
true
)
if (success) {
Log.d("Singular", "Third-party identifier set successfully")
}
}

// Clear the third-party identifier on user logout
fun onUserLogout() {
Singular.unsetGlobalProperty("third_party_identifier")
Log.d("Singular", "Third-party identifier cleared")
}

提示：对于需要跨会话持久化的标识符，请使用setGlobalProperty 。当标识符失效时（如用户注销时），务必调用unsetGlobalProperty 。

验证与故障排除

完成设置后，请验证集成：

  1. 确认api_secret 和firebase_app_id 已在Singular界面正确保存

  2. 验证在SDK初始化前已设置app_instance_id

  3. 使用GA4调试视图或实时报告确认事件接收状态

  4. 检查应用日志中的Singular SDK初始化错误

提示：GA4可能需要数分钟才能显示新事件。测试期间请使用DebugView进行近实时验证。

评论

请登录写评论。