> For the complete documentation index, see [llms.txt](https://helps.ptengine.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://helps.ptengine.com/cn/integrations/ga4.md).

# Google Analytics 4（GA4）的集成方法

Google Analytics 4（GA4）是一个用于收集和分析网站和应用访问者数据的下一代工具。 通过将Ptengine与GA4集成，可以将弹窗、页面编辑、A/B测试等交互数据发送到GA4，从而进行更详细的分析。 以下将详细说明集成方法。

## 开始之前 <a href="#prerequisites-for-integration" id="prerequisites-for-integration"></a>

* **GA4 的代码必须已经装在网站上**，而且要放在 Ptengine [基础代码](https://helps.ptengine.com/cn/start-guide/quick/tag-setup.md)**之前**（用 GTM 的话同理）
* 集成只支持**弹窗、悬浮条、页面编辑和 A/B 测试**，**重定向测试不支持**
* 集成是**档案级**的，开一次就对这个档案下所有体验生效，不用每建一个体验设一次

***

## 第一步：在 Ptengine 里打开集成 <a href="#how-to-enable-ga4-integration-in-ptengine" id="how-to-enable-ga4-integration-in-ptengine"></a>

{% stepper %}
{% step %}

### 切到 Experience，点右上角 ⚙

{% hint style="warning" %}
⚙ 菜单的内容**跟着当前所在的模块变**。在 Insight 下点 ⚙ 看到的是基础设置、热图设置那一组，**没有**集成入口。必须先切到 **Experience**。
{% endhint %}

菜单里选**外部应用集成**。

<figure><img src="https://2044586328-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FnucbKsG9WGIoxCpzyoHL%2Fuploads%2Fgit-blob-5a8a9e8a285b6dc18616ba012a39615d10b83226%2Fintegrations-ga4-01.png?alt=media" alt="Experience 模块下的 ⚙ 菜单，含外部应用集成"><figcaption></figcaption></figure>
{% endstep %}

{% step %}

### 在外部应用里点 Google Analytics 4 的“管理”

页面上有**外部应用**和 **API密钥**两个标签页，外部应用下目前是 Google Analytics 4 和 Shopify 两张卡片。已经开过的卡片右上角会标**已启用**。

<figure><img src="https://2044586328-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FnucbKsG9WGIoxCpzyoHL%2Fuploads%2Fgit-blob-eab12b1ab7b4d8da396f9d1867f57eb5acc23a53%2Fintegrations-ga4-02.png?alt=media" alt="外部应用集成页：GA4 与 Shopify 两张卡片"><figcaption></figcaption></figure>
{% endstep %}

{% step %}

### 打开“启用Google Analytics 4集成”开关

开关在详情页第 1 节的右上角，旁边会显示**最后启用时间**。

<figure><img src="https://2044586328-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FnucbKsG9WGIoxCpzyoHL%2Fuploads%2Fgit-blob-fb7ef03bb0aca93c9022fb05a544b1a918dcdc6c%2Fintegrations-ga4-03.png?alt=media" alt="GA4 集成详情页：启用开关与三条前提说明"><figcaption></figcaption></figure>

到这里 Ptengine 这边就完事了，剩下的都在 GA4 做。
{% endstep %}
{% endstepper %}

***

## 第二步：在 GA4 里把体验变量建成自定义维度 <a href="#setting-up-experience-variables-as-custom-dimensions-in-ga4" id="setting-up-experience-variables-as-custom-dimensions-in-ga4"></a>

开了集成之后，还要在 GA4 那边做映射，数据才认得出来。

{% stepper %}
{% step %}

### 登录 GA4，进入自定义定义

左侧主菜单 →**管理**→**自定义定义**→**创建自定义维度**。
{% endstep %}

{% step %}

### 建两个自定义维度

**要建两个**，分别对应体验名称和版本名称：

| 字段   | 填什么                                                         |
| ---- | ----------------------------------------------------------- |
| 维度名  | 自己起，建议就用下面事件参数的名字                                           |
| 范围   | 选**事件**                                                     |
| 说明   | 随意，写清楚这个维度是什么                                               |
| 事件参数 | 第一个填 `pt_experience_name`，第二个填 `pt_experience_version_name` |

事件参数在 GA4 里可以从下拉选，也可以直接输入或粘贴。GA4 这边的官方说明见 [Google 的文档](https://support.google.com/analytics/answer/9267735)。
{% endstep %}
{% endstepper %}

### GA4 能收到哪些事件 <a href="#events-that-can-be-sent-to-ga4" id="events-that-can-be-sent-to-ga4"></a>

Ptengine 推给 GA4 的是这三个事件：

* `pt_experience_impression` — 体验展示
* `pt_experience_close` — 体验关闭
* `pt_experience_click` — 体验点击

{% hint style="info" %}
高级模式下一个体验可能包含多个弹窗。为了不把 A/B 测试的数字算乱，**这种模式下每个 Page View 只发一包事件**。
{% endhint %}

***

## 第三步：确认数据真的发出去了 <a href="#validating-the-integration-configuration" id="validating-the-integration-configuration"></a>

映射做完后，用浏览器开发者工具看一眼网络请求就能确认：

{% stepper %}
{% step %}

### 打开带弹窗的页面，右键 →“检查”

{% endstep %}

{% step %}

### 切到 Network（网络）标签，搜 `analytics.google.com`

把请求过滤成只剩 GA4 的。
{% endstep %}

{% step %}

### 看请求里有没有 `pt_experience_impression` 之类的事件名

看得到就说明 Ptengine 这边已经正常在发。
{% endstep %}
{% endstepper %}

{% hint style="warning" %}
**浏览器里看到了，不等于 GA4 报告里马上有。** GA4 侧处理数据需要时间，开了集成后一般要 **24～48 小时**数据才会出现在 GA4 的报告里。
{% endhint %}

***

## 关于GA4集成故障 <a href="#about-ga4-integration-issues" id="about-ga4-integration-issues"></a>

如果您使用Google Tag Manager（GTM）并通过“Google标签”安装，GA4可能无法收集来自Ptengine的数据。

### **解决方法** <a href="#solution" id="solution"></a>

为了使Ptengine与GA4集成顺利进行，请将以下标签放在**Ptengine基础代码之前**。

```
<script>
var ptTimer = setInterval(function(){
    if(dataLayer){
        clearInterval(ptTimer);
        if (typeof(gtag) === 'undefined') { 
                    gtag = function() { dataLayer.push(arguments); };
                    gtag('js', new Date());
                    gtag('config', 'G- set your GA4 sid');
                }
    }
},500)
</script>
```

※需要将代码中的“G- set your GA4 sid”替换为您网站的GA4 sid。

🔰如何获取GA4 sid

1.进入GA4的管理界面。

2.点击“数据收集和修正”中的“数据流”按钮。

3.选择指定的数据流，可以确认“测量ID”。

确认“测量ID”后，将上述“G- set your GA4 sid”替换为“测量ID”，gTag配置即完成。

***

## 在 GA4 里建数据探索和细分 <a href="#creating-ga4-data-exploration-and-adding-segments" id="creating-ga4-data-exploration-and-adding-segments"></a>

进入“探索”，选择数据探索的类型或从空白状态开始。

在左侧的“变量”面板中，点击“细分”旁边的加号图标。在“创建新细分”页面上，点击“用户组”。

输入细分的名称。例如，特定的Experience或版本名称。

展开“添加说明”下拉列表，点击“事件”，然后选择“pt\_experience\_impression”或“pt\_experience\_click”（取决于要创建的细分）。

点击“添加参数”下拉列表。

点击“自定义”并选择pt\_experience\_name。

选择或指定要为其创建此细分的特定Experience名称。

如果要指定特定版本，请再次点击“添加参数”下拉列表以添加另一个参数，点击pt\_experience\_version\_name，并选择或指定要为其创建此细分的特定版本名称。

点击“保存”后，可以在报告中使用该细分。

***

## 在 GA4 里建受众 <a href="#creating-ga4-audiences" id="creating-ga4-audiences"></a>

转到“管理”，选择“受众”，然后点击“受众”。

在“创建受众”屏幕上，展开“添加新条件”下拉列表，点击“事件”，然后选择**pt\_experience\_impression**或**pt\_experience\_click**（取决于要创建的受众）。 例如，如果要为显示退出意图弹窗的用户创建受众，请选择事件**pt\_experience\_impression**，点击“添加参数”选择**pt\_experience\_name**，将条件设置为“包含”，然后输入“Experience名称”。

如果在下拉列表中找不到事件或事件属性，数据可能尚未同步到GA4。在这种情况下，您可以点击“创建事件”或“注册新定义”来创建新事件。

点击“保存”保存受众。通常，数据反映在受众中可能需要24-48小时。

创建受众后，可以在报告中使用它。

***

## 相关页面 <a href="#related-pages" id="related-pages"></a>

* [基础代码的安装](https://helps.ptengine.com/cn/start-guide/quick/tag-setup.md)
* [通过GTM安装](https://helps.ptengine.com/cn/start-guide/othertag/tag-gtm.md)
* [与GA的数据差异](https://helps.ptengine.com/cn/faq/data/ga-comparison.md) — 两边数字对不上时先看这个
* [营销活动的UTM标签](https://helps.ptengine.com/cn/insight/data-center/campaign-utm.md)
