---
title: Google Tag Manager 集成
description: 将 GTM 容器 ID 添加到 docs.json，即可在每个页面加载 Google Tag Manager，并在 GTM 中管理分析和跟踪标签。
---

> **For AI agents:** the complete documentation index is at [llms.txt](/docs/llms.txt). Append `.md` to any page URL for its markdown version.

将 GTM 容器 ID 添加到 `docs.json`，即可在文档站点的每个页面加载 Google Tag Manager。之后，您的营销团队可以完全在 GTM 中配置分析、转化像素和事件跟踪。

<Info>
GTM 容器 ID 以 `GTM-` 开头。如果您只需要 Google Analytics，请参阅 [Google Analytics 集成](/cn/integrations/google-analytics)以使用更简单的设置。
</Info>

## 何时使用 GTM

在以下情况下使用 Google Tag Manager：

- **多个跟踪工具** - GA4、Facebook Pixel、LinkedIn 等
- **由营销团队控制** - 让营销人员无需开发人员协助即可添加标签
- **高级触发器** - 跟踪按钮点击、表单提交和视频观看
- **A/B 测试集成** - 连接 Google Optimize 等工具

如果只需要基本分析，直接添加 GA4 会更简单。

## 获取容器 ID

1. 转到 [Google Tag Manager](https://tagmanager.google.com/)
2. 选择您的账号和容器（或创建新的账号和容器）
3. 从页面顶部复制 **Container ID**（以 `GTM-` 开头）

## 将 GTM 添加到文档

将容器 ID 添加到您的 `docs.json`：

```json docs.json
{
  "name": "My Docs",
  "integrations": {
    "gtm": {
      "tagId": "GTM-XXXXXXX"
    }
  }
}
```

将 `GTM-XXXXXXX` 替换为您的实际容器 ID。

## Cookie 同意

如果需要 Cookie 同意横幅，您需要负责进行设置。Jamdesk 会在每个页面加载您的 GTM 容器，因此您配置的任何标签都会对所有访问者触发。如果您的读者受 GDPR、CCPA 或类似法规约束，请在 GTM 中配置[同意模式](https://support.google.com/tagmanager/answer/10718549)，或使用同意管理平台。Jamdesk 也可以在获得同意后再加载 GTM。本主题请参阅 [Cookie 同意](/cn/integrations/cookie-consent)。

## 通过 GTM 设置 GA4

如果您希望通过 GTM 使用 GA4，而不是直接添加 GA4：

1. 在 GTM 中转到 **Tags** → **New**
2. 选择 **Google Analytics: GA4 Configuration**
3. 输入您的 GA4 Measurement ID（以 `G-` 开头）
4. 将触发器设置为 **All Pages**
5. **Publish** 您的容器

<Warning>
如果您通过 GTM 配置 GA4，请不要同时在 `docs.json` 中直接添加 GA4，否则会造成重复跟踪。
</Warning>

## 验证安装

### 使用 GTM 预览模式

1. 在 GTM 中点击右上角的 **Preview**
2. 输入您的文档站点 URL
3. 调试窗口会显示每个页面上触发的标签

### 使用浏览器开发者工具

1. 使用开发者工具（F12）打开您的站点
2. 转到 **Network** 标签页
3. 筛选 `gtm.js` 或 `googletagmanager`
4. 您应该会看到正在发出的请求

## 文档常用 GTM 标签

### 跟踪出站链接

创建一个标签，跟踪用户点击外部链接的情况：

1. **Tag**：Google Analytics: GA4 Event
2. **Event Name**：`click`
3. **Trigger**：Click - Just Links，其中 Click URL 不包含您的域名

### 跟踪搜索使用情况

跟踪用户与搜索功能交互的情况：

1. **Tag**：Google Analytics: GA4 Event
2. **Event Name**：`search`
3. **Trigger**：与您的搜索交互匹配的自定义事件

### 跟踪页面停留时间

了解用户阅读页面所花费的时间：

1. **Tag**：Google Analytics: GA4 Event
2. **Event Name**：`timing`
3. **Trigger**：计时器触发器（例如每 30 秒触发一次）

## 排查常见 GTM 问题

<Accordion title="标签未触发">
  1. **检查容器 ID** - 必须以 `GTM-` 开头
  2. **Publish 您的容器** - 未发布的更改不会显示在您的站点上
  3. **使用 Preview 模式** - GTM 的预览会显示每个页面上触发的标签
</Accordion>

<Accordion title="Google Analytics 中存在重复数据">
  如果您同时通过以下两种方式配置了 GA4：
  - 直接在 `docs.json` 中配置（`integrations.ga4`）
  - 通过 GTM 配置为 GA4 标签

  您会获得重复的页面浏览量。请移除其中一种配置。
</Accordion>

## 相关文章

<Columns cols={2}>
  <Card title="Google Analytics" icon="chart-simple" href="/cn/integrations/google-analytics">
    直接添加 GA4，无需 GTM
  </Card>
  <Card title="项目分析" icon="chart-line" href="/cn/setup/project-analytics">
    查看 Jamdesk 内置的分析功能
  </Card>
</Columns>