GTM 桥接 & GA4 事件桥接
通过双向 dataLayer 同步与兼容 GA4 的 API，将 Google Analytics 4 的定量遥测与 MousePlayer 会话回放的定性信息相结合。
1. 架构概览 & 功能
现代 Web 分析常受一种根本性数据孤岛影响：定量平台（如 Google Analytics 4）报告网站上 发生了什么 ，而定性的会话回放工具解释 为什么 会发生。 MousePlayer GTM & GA4 桥接 在浏览器 JavaScript 运行时中建立双向同步通道，消除这一鸿沟。
启用后，跟踪脚本会初始化两个专用核心模块：
- 会话回放导出器（initGa4SessionBridge）： 会话一旦建立，就自动将活跃录制的会话标识符（
mp_session_id）和直接回放 URL（mp_session_url）推送到网站的数据层。 - GA4 事件接入器（initDataLayerBridge）： 向数据层数组附加非破坏性监听器。为 GA4 推送的任何自定义电商或行为事件，都会立即作为自定义事件（
ce）同步至 MousePlayer 分析数据库，包括全部数值与字符串参数。
支持自定义 dataLayer 对象： 如果 Web 应用未采用标准的 dataLayer 而使用自定义 JavaScript 数组名称（例如 xyzDataLayer），引擎会根据配置的 gtm_datalayer_name 参数动态适配，无需手动修改代码。
2. 战略业务价值
将会话回放链接直接集成到企业分析管道，可带来多项显著的运营优势：
| 业务能力 | 运营影响 |
|---|---|
| 转化率优化（CRO） | 数字分析人员可找出 GA4 转化漏斗中的摩擦点，并立即打开在特定结账步骤放弃购物车的用户录制。 |
| 收入归因 & 审计 | 可通过查看促成购买的准确指针轨迹、点击和视口状态，审计高价值电商交易。 |
| 加速技术调试 | QA 工程团队可将 GA4 JavaScript 异常事件或 API 错误日志直接关联到可视化屏幕录制，无需手动重现缺陷。 |
| 解决客户支持问题 | 支持工单包含用户会话 ID 时，客服可查看客户确切的会话回放，大幅缩短解决时间。 |
3. Google Tag Manager 配置指南
要在 Google Tag Manager 中采集回放 URL 并传至 Google Analytics 4，必须配置三类独立的 GTM 资源：
第 1 步：创建数据层变量
在 GTM 工作区，前往 变量 → 用户定义的变量 ，创建两个类型为 数据层变量的变量：
- 变量名称：
dlv - mp_session_id• 数据层变量名称：mp_session_id - 变量名称：
dlv - mp_session_url• 数据层变量名称：mp_session_url
第 2 步：创建启用触发器
前往 触发器 → 新建 ，选择触发器类型 自定义事件。配置以下参数：
- 事件名称：
mp_session_ready - 此触发器的触发条件： 所有自定义事件
第 3 步：配置 GA4 事件标签
新建类型为 Google Analytics：GA4 事件 的标签，将会话链接传至 GA4 媒体资源：
4. 在 GA4 中配置探索（自定义报告）
部署 GTM 标签后，GA4 开始以事件参数形式接收回放 URL。要在自定义探索报告中分析这些数据，必须先将此参数注册为自定义维度。
在 GA4 管理中注册自定义维度
在 Google Analytics 4 界面中，前往 管理 → 数据展示 → 自定义定义 ，点击 创建自定义维度：
- 维度名称：
MousePlayer Session URL - 范围： 事件 （或 会话 ，适用于附加到会话范围参数的情况）
- 事件参数：
mp_session_url
创建会话检查探索
在 GA4 的 探索 区域，新建 自由形式 探索，检查单个用户旅程：
- 行： 添加
Event name、Transaction ID（适用于电商）或Landing page。 - 列 / 维度： 包含新建的自定义维度
MousePlayer Session URL。 - 值： 添加
Event count或Total users。
生成的报告表会在 GA4 指标旁显示可直接点击的 URL，可即时从统计异常值切换至可视化回放。
5. 将回放 URL 集成到 GA4 默认报告
除探索外，还可使用 GA4 报告库，将自定义维度集成到标准默认报告（如 流量获取、 网页和屏幕或 电商购买）中。
修改标准报告表
- 在 GA4 中打开任意默认详细报告（例如 报告 → 互动度 → 网页和屏幕）。
- 点击右上角的 自定义报告 铅笔图标（需要管理权限）。
- 在右侧面板的 报告数据下，点击 维度。
- 将
MousePlayer Session URL添加到主要或次要维度列表，并设为可见。 - 点击 保存 → 保存对当前报告所做的更改。
保存后，查看标准流量获取或转化表的任何分析人员，都可将 MousePlayer Session URL 添加为次要维度，即时直观检查标准流量细分中的访客行为。
6. JavaScript API & GA4 / GTM 兼容性参考
MousePlayer 提供直观且兼容 GA4 的 JavaScript API（采用标准的 gtag()风格命令）以及公共全局对象（window.MousePlayer）。开发者可据此在控制台查询会话 URL、附加 B2B 客户 ID，并将回放链接注入第三方帮助台或错误跟踪工具。
1. 直接注入回放 URL（Intercom / Zendesk / 自定义桥接）
可在浏览器控制台或任意自定义脚本中，使用 window.MousePlayer.getSessionUrl()直接获取活跃访客会话的完整回放 URL：
2. 设置自定义 B2B 客户 ID（user_id）
为识别已登录的 SaaS 或 B2B 客户，可在初始脚本配置时，或在运行时通过 GA4 语法，传入自定义的 user_id （如数据库 ID、电子邮箱或 UUID）：
3. 异步数据获取方法
可使用标准 GA4 回调语法，在自定义标签管理脚本中异步获取会话元数据：
此处提及的所有商标均属于各自所有者。MousePlayer 与这些提供商不存在商业关系。