Google Analytics 集成

需要开发者协助

您需要开发团队的帮助来设置此集成。请与他们分享本指南。

将同一个用户 ID 发送到 Google Analytics 4 和 Pushwoosh，两个工具就会把访问您网站或应用的同一个人视为同一个用户。这样，您就可以向在 Google Analytics 中分析的用户发送消息，并基于 Google Analytics 数据构建 Pushwoosh 细分。

集成概述

集成类型

目的地： Google Analytics 受众和 Google Analytics 的 BigQuery 导出数据会成为 Pushwoosh 细分。用户 ID 由您的网站或应用分别发送到每个工具。Pushwoosh 不会向 Google Analytics 发送数据。

先决条件

• Pushwoosh 账户，以及在发送用户 ID 的网站或应用中集成的 Pushwoosh SDK（Web、Android 或 iOS）。
• 从同一网站或应用收集数据的 Google Analytics 4 媒体资源。

要导入 Google Analytics 受众，您还需要：

• 一个 Google Cloud 服务帐户及其 JSON 密钥。请参阅 Create and delete service account keys。
• 在该服务帐户所属的项目中启用 Google Analytics Data API 和 Admin API。
• 该服务帐户在 Google Analytics 媒体资源上拥有 Viewer 角色。请参阅 Add, edit, and delete users and user groups。

要查询 BigQuery 导出数据，您还需要：

• 已关联到 BigQuery 的 Google Analytics 4 媒体资源。请参阅 Set up BigQuery Export。
• 具有 BigQuery Data Viewer 和 BigQuery Job User 角色的服务帐户密钥。请参阅 BigQuery roles and permissions。

集成如何工作？

Pushwoosh 通过 ID 匹配用户：

1. 您的网站或应用将同一个用户 ID 发送到 Google Analytics 和 Pushwoosh。
2. Pushwoosh 从 Google Analytics 受众或您的 BigQuery 导出数据中读取用户 ID。
3. 当用户的 ID 与 Pushwoosh User ID 匹配时，该用户即进入细分。

不同来源的细分刷新方式不同：

• 基于受众的细分在使用期间大约每天刷新一次。
• 基于 BigQuery 的细分反映截至前一天的活动。

设置集成

设置分为两部分。首先，您的开发人员从网站或应用发送用户 ID。然后，您在 Control Panel 中基于 Google Analytics 数据构建细分。

1. 与开发人员一起选择用户 ID。
2. 开发人员从您的网站或移动应用将其发送到 Google Analytics 和 Pushwoosh。
3. 可选：基于 Google Analytics 数据构建 Pushwoosh 细分。之后，您可以像使用其他细分一样使用它。

将用户 ID 发送到 Google Analytics 和 Pushwoosh

这部分由您的开发人员完成。请与他们分享以下各节。

选择用户 ID

使用您自己的系统中已为每个用户分配的标识符，例如数据库中的账户 ID。同一个值既作为用户 ID 发送到 Google Analytics，也作为 User ID 发送到 Pushwoosh。

请勿在用户 ID 中使用个人信息

Google Analytics 政策不允许在用户 ID 中包含个人信息。请勿使用电子邮件地址、电话号码或其他个人信息。

请在用户登录或以其他方式被识别时设置该 ID。

从网站发送用户 ID

在 Google 代码的 user_id 参数中将 ID 传递给 Google Analytics。如果您使用 Google Tag Manager，请改为在 Google 代码配置中设置 user_id 字段。请参阅 Google 文档中的 Send user IDs。

JavaScript

gtag('config', 'G-XXXXXXXXXX', {
  'user_id': 'USER_ID'
});

使用 Web Push SDK 将同一个 ID 传递给 Pushwoosh：

JavaScript

Pushwoosh.push((api) => {
  api.registerUser('USER_ID');
});

从移动应用发送用户 ID

移动应用通过 Firebase 向 Google Analytics 4 发送数据。使用 Firebase Analytics 的 setUserId 设置 ID（请参阅 Firebase 文档中的 Set a user ID），并使用 Pushwoosh SDK 设置相同的值。

Android

Java

FirebaseAnalytics.getInstance(context).setUserId("USER_ID");
Pushwoosh.getInstance().setUserId("USER_ID");

iOS

Swift

Analytics.setUserID("USER_ID")
Pushwoosh.sharedInstance().setUserId("USER_ID")

基于 Google Analytics 数据创建细分

这部分由您在开发人员发送用户 ID 之后，在 Control Panel 中完成。Pushwoosh 可以通过两种方式将 Google Analytics 数据转换为细分，两种方式都通过外部细分实现：

• 导入 Google Analytics 受众：选择您已在 Google Analytics 中构建的受众。无需 SQL，也无需 BigQuery。
• 查询 BigQuery 导出数据：针对 Google Analytics 导出到 BigQuery 的原始事件编写您自己的 SQL，用于受众无法表达的条件。

导入 Google Analytics 受众

请您的开发人员或 Google Cloud 管理员在 Google Cloud 和 Google Analytics 中完成以下步骤：

1. 准备一个服务帐户及其 JSON 密钥。请参阅 Google Cloud 文档中的 Create and delete service account keys。
2. 在该服务帐户所属的 Google Cloud 项目中，启用 Google Analytics Data API 和 Google Analytics Admin API。
3. 在 Google Analytics 中，前往 Admin → Property access management，以 Viewer 角色添加该服务帐户的电子邮件地址。在 Google Cloud IAM 中授予的角色不会提供对 Google Analytics 的访问权限。

然后在 Control Panel 中完成以下步骤：

1. 创建一个外部细分，并将 数据库类型 设置为 Google Analytics 4 audience。

2. 输入 GA4 媒体资源 ID。您可以在 Google Analytics 的 Admin → Property details 中找到它。

3. 将第一个列表中准备的 JSON 密钥粘贴到 Service account JSON 中。

4. 点击 加载受众群体 并选择 受众群体。

   

5. 点击 检查连接。

6. 点击 创建。

当 Pushwoosh 读取整个细分时（例如向该细分发送活动或 journey，或计算其规模时），会刷新该细分：

• 如果数据不足 24 小时，Pushwoosh 会直接使用，因为 Google Analytics 大约每天更新一次受众成员。
• 如果数据超过 24 小时，Pushwoosh 会使用当前数据，并在后台刷新该细分。
• 如果数据超过 72 小时，Pushwoosh 会等待刷新完成。

细分每天最多只能刷新一次。如果细分已超过一天未刷新，请在发送前提前计算细分规模。这会在后台启动刷新，使发送使用更新的数据。

查询 BigQuery 导出数据

如果您将 Google Analytics 4 数据导出到 BigQuery，就可以使用针对用户事件的任意 SQL 条件来选择用户，例如过去 30 天内进行过购买的所有用户。

请您的开发人员或 Google Cloud 管理员在 Google Cloud 和 Google Analytics 中完成以下步骤：

1. 将您的 Google Analytics 4 媒体资源关联到 BigQuery 项目，并开启每日导出。请按照 Google 文档中的 Set up BigQuery Export 操作。

   之后，Google Analytics 会将每天的事件写入名为 analytics_<property ID> 的数据集中名为 events_YYYYMMDD 的表。您在前面几节中发送的用户 ID 位于 user_id 列。

2. 创建一个具有 BigQuery Data Viewer 和 BigQuery Job User 角色的服务帐户密钥。检查连接 和 检查查询 会在您的项目中运行测试查询作业，因此没有 BigQuery Job User 角色时会失败。

然后，在 Control Panel 中创建一个外部细分，将 数据库类型 设置为 Google BigQuery。输入用于连接的服务帐户密钥，以及返回目标用户 ID 的查询。

例如，以下查询返回过去 30 天内进行过购买的用户。请将 my-project 替换为您的 Google Cloud 项目 ID，将 analytics_123456789 替换为您的数据集名称：

SQL

SELECT DISTINCT user_id
FROM `my-project.analytics_123456789.events_*`
WHERE event_name = 'purchase'
  AND user_id IS NOT NULL
  AND _TABLE_SUFFIX >= FORMAT_DATE('%Y%m%d', DATE_SUB(CURRENT_DATE(), INTERVAL 30 DAY))

由于 Google Analytics 每天导出一次数据，细分反映的是截至前一天的活动。

如何判断集成是否正常工作？

• 用户 ID：在 Pushwoosh 中，前往 受众 → 用户探索器，按 User ID 搜索您发送到 Google Analytics 的某个 ID。如果找到该用户，说明两个工具拥有相同的 ID。
• 细分：在 受众 → 外部分群 中，该细分的状态为 有效。要查看匹配的用户数，请检查细分规模。

问题排查

加载受众群体或检查连接时显示错误

这两个按钮都会使用服务帐户密钥登录并读取该媒体资源的受众列表，表单会显示 Google Analytics 返回的错误。请检查：

• Service account JSON 是服务帐户密钥。其他 Google 凭据文件会被拒绝。
• GA4 媒体资源 ID 是 Admin → Property details 中的编号。
• 该服务帐户在 Google Analytics 的 Admin → Property access management 中拥有 Viewer 角色。在 Google Cloud IAM 中授予的角色无效。
• 在该服务帐户所属的 Google Cloud 项目中已启用 Google Analytics Admin API。

受众列表为空

该媒体资源还没有任何受众。请在 Google Analytics 的 Admin → Audiences 中创建一个，然后再次点击 加载受众群体。

没有用户进入细分

• 确保已启用 Google Analytics Data API。检查连接 不会测试它，但 Pushwoosh 需要它来读取受众成员。
• 确保您的网站或应用将同一个用户 ID 发送到 Google Analytics 和 Pushwoosh。只有 Google Analytics 用户 ID 与 Pushwoosh User ID 匹配的用户才会进入细分。Google Analytics 仅通过匿名客户端 ID 识别的用户不会进入细分。

BigQuery 的检查连接或检查查询失败

这两项检查都会在您的 Google Cloud 项目中运行测试查询作业，而不读取任何数据。请检查：

• 该服务帐户同时拥有 BigQuery Data Viewer 和 BigQuery Job User 角色。没有 BigQuery Job User，两项检查都无法运行。
• 查询使用了您的项目 ID 和 analytics_<property ID> 数据集名称，并且导出已至少写入一个每日 events_YYYYMMDD 表。
• 查询恰好返回一列，名为 user_id。