将自定义事件推送到 Google Tag Manager 和 Analytics

[Discourse]

在将 Google 标签管理器与 Google Analytics 集成的讨论基础上继续：

将自定义事件推送到 Google 标签管理器和 Analytics

本指南说明如何配置您的 Discourse 站点，以便将自定义事件发送到 Google 标签管理器 (GTM) 和 Google Analytics，从而允许您跟踪特定的用户互动。

所需用户级别：管理员

先决条件

在实施自定义事件之前，请确保您已：

1. 按照为 Analytics 设置 Google 标签管理器指南，在您的 Discourse 站点上配置了 Google 标签管理器
2. 将您的 GTM 容器 ID 添加到您站点的 gtm container id 设置中
3. 更新您站点的 content security policy script src 设置，以允许 Google 脚本

添加自定义事件

创建主题组件

1. 导航到 管理员 > 自定义 > 组件
2. 点击“新建”并选择“创建新组件”
3. 为您的组件命名
4. 选择 JS 选项卡并添加您的代码。例如，下面的代码会捕获 appEvent 触发器，并将以下事件推送到 dataLayer：

• post:liked
• post:created
• topic:created

import { apiInitializer } from "discourse/lib/api";

export default apiInitializer((api) => {
  window.dataLayer = window.dataLayer || [];

  // 跟踪帖子点赞
  api.onAppEvent("page:like-toggled", (post, likeAction) => {
    let topic = post.topic;
    if (post && topic && likeAction && likeAction.acted) {
      window.dataLayer.push({
        'event': 'postLiked',
        'postId': post.id
      });
    }
  });

  // 跟踪新帖子
  api.onAppEvent("post:created", post => {
    if (post) {
      window.dataLayer.push({
        'event': 'postCreated',
        'postId': post.id
      });
    }
  });

  // 跟踪新主题
  api.onAppEvent("topic:created", (post, composerModel) => {
    if (post) {
      window.dataLayer.push({
        'event': 'topicCreated',
        'topicCategory': composerModel.get("category.name"),
        'topicId': post.topic_id
      });
    }
  });
});

5. 保存组件
6. 将组件添加到您站点上的所有活动主题中

可用事件

所有可用的触发事件都在此处列出：AppEvents 触发器参考

配置 GTM

创建触发器

1. 访问 https://tagmanager.google.com/
2. 从侧边菜单中选择“触发器”
3. 点击“新建”
4. 为您的触发器命名
5. 选择“自定义事件”作为触发器类型
6. 输入事件名称（例如 postCreated）
7. 将触发器设置为在“所有自定义事件”上触发

创建一个数据层变量

1. 从 GTM 侧边菜单中选择“变量”
2. 在用户定义变量部分中点击“新建”
3. 为您的变量命名
4. 选择“数据层变量”作为变量类型
5. 输入数据层变量名称（例如 postCreated）
6. 将数据层版本设置为“版本 2”

创建用于事件跟踪的 Google 标签

截至 2024 年，推荐的方法是使用新的“Google Tag”模板，而不是旧的“Google Analytics: GA4 Event”标签类型。“Google Tag”可更好地与 GA4 集成，并包含对 Consent Mode v2 的内置支持。

1. 从 GTM 侧边菜单中选择“标签”
2. 点击“新建”
3. 为您的标签命名（例如“GT - Post Created”）
4. 在标签配置下：
   • 选择“Google Tag”
   • 选择您的 GA4 配置（如果这是您的第一个标签，则创建一个新的）
   • 对于“事件名称”，输入一个遵循 GA4 命名约定的描述性名称（例如 post_created）
   • 在“配置设置”下，点击“添加行”以包含您的数据层变量：
     • 配置参数：（例如 postId）
     • 值：您的数据层变量（例如 {{postCreated}}）
5. 在“触发条件”下：
   • 选择您先前创建的自定义事件触发器

如果您当前正在使用“Google Analytics: GA4 Event”标签，它们将继续工作，但新的实现应使用“Google Tag”模板以获得更好的未来兼容性和功能。

事件命名要求

GA 对事件名称有特定的要求：

• 使用 snake_case（小写字母加下划线）
• 最大长度为 40 个字符
• 只能包含字母数字字符和下划线

测试您的 Google 标签

1. 在 GTM 中点击“预览”按钮
2. 导航到您的 Discourse 站点
3. 执行您想要跟踪的操作（例如创建帖子）
4. 在 GTM 预览模式中：
   • 验证您的自定义事件是否出现在左侧面板中
   • 检查您的 Google 标签是否正确触发
   • 确认所有参数是否按预期传递
5. 在 Google Analytics 中：
   • 导航到配置 > 事件
   • 您的自定义事件应在触发后出现在列表中
   • 注意：新的事件可能需要长达 24 小时才能出现在 GA4 报告中

您可以使用 GA4 调试视图在测试期间查看实时事件数据。

故障排除

如果在 GTM 中看不到事件：

1. 检查您的 GTM 容器 ID 是否在 Discourse 中正确设置
2. 确保您的主题组件已添加到所有活动主题中
3. 添加 console.log 语句以验证事件是否触发：

api.onAppEvent("post:created", post => {
  console.log("post:created event triggered");
  if (post) {
    window.dataLayer.push({
      'event': 'postCreated',
      'postId': post.id
    });
  }
});

4. 使用 Simple Data Layer Viewer Chrome 扩展程序来监控数据层
5. 如果看到内容安全策略 (CSP) 错误，请参阅上面引用的先决条件，并查看 Mitigate XSS Attacks with Content Security Policy 以获取更多步骤。

如果您配置了 ga universal tracking code 站点设置，请将其清空，因为 GTM 将处理跟踪脚本。