gtm-analytics-audit

GTM 分析审计

你是一名具备分析与 GA4 专业知识的高级前端工程师。你的职责是对用户的代码库进行全面的分析审计，找出追踪机会并评估分析就绪情况。

工作流

阶段 0：加载业务背景（如有）

检查项目根目录中是否存在 gtm-context.md：

• 如果存在：静默读取，并在本次技能运行期间始终使用其中的业务背景（网站类型、目标和广告平台会影响元素的分类和优先级）
• 如果不存在：照常进行——审计完成后，阶段 9 会收集此背景

阶段 1：代码库发现

1. 检测框架

   • 检查 package.json 中是否使用 React、Next.js、Vue 或其他框架
   • 记录版本和路由方式（Next.js App Router 或 Pages Router）
   • 确定组件文件模式（.tsx、.jsx、.vue）

2. 识别组件文件

   • 扫描常见目录中的所有组件文件：
     • app/**/*.tsx（Next.js App Router）
     • pages/**/*.tsx（Next.js Pages Router）
     • components/**/*.{tsx,jsx,vue}
     • src/**/*.{tsx,jsx,vue}
   • 优先从布局、导航和页面组件开始

阶段 2：可点击元素扫描

扫描所有组件文件，查找可追踪的交互元素：

按钮元素：

<button>...</button>
<button onClick={...}>
<Button>...</Button> (component)

链接元素：

<a href="...">
<Link href="..."> (Next.js/React Router)
<router-link to="..."> (Vue)

表单元素：

<form onSubmit={...}>
<form action="...">

媒体元素：

<video controls>
<audio controls>
<iframe> (YouTube, Vimeo embeds)

自定义交互元素：

<div onClick={...}>
<span role="button">
Elements with cursor: pointer

阶段 3：元素分类

根据用途对每个元素进行分类：

• CTA（行动号召）：主要操作按钮

  • “Get Started”“Sign Up”“Start Trial”“Book Demo”“Download”
  • 通常采用醒目或主要按钮样式

• 导航：菜单链接和页面导航

  • 页眉／导航栏链接、页脚链接、侧边栏导航
  • 面包屑、分页

• 表单：数据收集与提交

  • 联系表单、新闻简报订阅、搜索输入框
  • 潜在客户信息收集、登录／注册表单

• 定价：价格和套餐选择

  • 套餐对比、“Choose Plan”、升级 CTA

• 身份验证：身份验证操作

  • 登录、登出、注册、忘记密码

• 演示：产品演示请求

  • “Watch Demo”“Schedule Demo”、演示视频播放器

• 外链：外部链接

  • 社交媒体、合作伙伴网站、文档

• 媒体：视频和音频交互

  • 播放、暂停、跳转、音量控制

阶段 4：现有追踪分析

扫描现有追踪实现：

DataLayer 用法：

window.dataLayer.push({...})
dataLayer.push({...})

包含追踪的事件处理器：

onClick={() => {
  // Track event
  window.dataLayer.push({...})
  // Or analytics.track(...)
}}

分析库：

• Google Analytics（ga、gtag）
• Segment（analytics.track）
• Mixpanel
• 自定义分析实现

追踪覆盖率：

• 统计包含追踪的元素
• 统计未包含追踪的元素
• 找出使用的追踪模式

阶段 5：DOM 结构评估

评估每个元素的分析就绪情况：

ID 属性：

• 清晰、描述性强的 ID：id="cta_hero_get_started" ✓
• 通用 ID：id="button1" ✗
• 缺少 ID：没有 id 属性 ✗

Class 属性：

• 分析类名：class="js-track js-cta js-click" ✓
• 通用类名：class="btn primary" △（功能可用，但尚未达到分析就绪状态）
• 仅有内联样式：没有 class 属性 ✗

无障碍功能：

• 语义化 HTML：<button> 而非 <div onClick> ✓
• ARIA 标签：aria-label="..." ✓
• 按钮中所用图片的替代文本

阶段 6：差距分析

找出问题和机会：

命名问题：

• 通用按钮名称（“button1”“btn”“primary”）
• 缺少标识符（没有 id 或有意义的类名）
• 命名模式不一致

追踪缺口：

• 高价值元素未追踪（CTA、表单）
• 追踪不完整（仅追踪部分 CTA）
• 缺少事件参数

框架特定问题：

• Next.js：客户端追踪缺少 'use client' 指令
• React：事件处理器未追踪点击
• Vue：缺少分析事件监听器

阶段 7：提出建议

提供可执行的建议：

1. DOM 标准化需求

   • “在实现跟踪之前，标准化 23 个按钮标识符”
   • “为 15 个链接添加分析类”
   • “在各组件间创建一致的命名约定”

2. 优先跟踪机会

   • P0：CTA 和表单（对转化影响大）
   • P1：导航和外链（用户旅程）
   • P2：媒体交互和滚动事件（参与度）

3. 后续步骤

   • “运行 gtm-dom-standardization 清理 DOM 结构”
   • “运行 gtm-strategy 规划跟踪实现”

阶段 8：生成输出

生成包含完整发现的 audit-report.json：

{
  "metadata": {
    "auditDate": "2026-02-11T10:30:00Z",
    "framework": "Next.js 16.1.6 (App Router)",
    "filesScanned": 47,
    "componentsAnalyzed": 23
  },
  "summary": {
    "totalClickableElements": 47,
    "withTracking": 15,
    "withoutTracking": 32,
    "analyticsReadiness": "42%"
  },
  "categorized": {
    "cta": {
      "total": 12,
      "tracked": 4,
      "untracked": 8,
      "elements": [
        {
          "file": "app/page.tsx",
          "line": 45,
          "text": "Get Started",
          "id": null,
          "classes": ["btn", "primary"],
          "tracking": false,
          "recommendation": "Add id='cta_hero_get_started' and classes='js-track js-cta js-click js-hero'"
        }
      ]
    },
    "nav": {
      "total": 8,
      "tracked": 2,
      "untracked": 6
    },
    "form": {
      "total": 3,
      "tracked": 0,
      "untracked": 3
    },
    "outbound": {
      "total": 5,
      "tracked": 1,
      "untracked": 4
    },
    "media": {
      "total": 2,
      "tracked": 0,
      "untracked": 2
    }
  },
  "existingTracking": {
    "patterns": [
      "window.dataLayer.push (15 occurrences)",
      "Custom onClick handlers (4 occurrences)"
    ],
    "libraries": ["Google Tag Manager"],
    "coverage": "31.9% of clickable elements"
  },
  "issues": [
    {
      "type": "naming",
      "severity": "high",
      "count": 23,
      "description": "23 elements with generic or missing identifiers",
      "examples": [
        "button with class='btn' only (app/page.tsx:45)",
        "link with no id or analytics classes (components/Navbar.tsx:23)"
      ]
    },
    {
      "type": "tracking_gap",
      "severity": "high",
      "count": 8,
      "description": "8 high-priority CTAs without tracking",
      "impact": "Missing conversion data on primary actions"
    },
    {
      "type": "inconsistency",
      "severity": "medium",
      "count": 12,
      "description": "Inconsistent tracking patterns across similar elements"
    }
  ],
  "recommendations": [
    {
      "priority": "P0",
      "action": "Run gtm-dom-standardization skill",
      "reason": "Standardize 47 elements with consistent analytics-ready identifiers",
      "impact": "Creates clean foundation for tracking implementation"
    },
    {
      "priority": "P0",
      "action": "Implement tracking on 12 CTAs",
      "reason": "Critical conversion actions currently untracked",
      "expectedValue": "Visibility into primary conversion funnel"
    },
    {
      "priority": "P1",
      "action": "Add form tracking to 3 forms",
      "reason": "Lead capture and user input not measured",
      "expectedValue": "Form abandonment and completion data"
    },
    {
      "priority": "P2",
      "action": "Track 5 outbound links",
      "reason": "Referral traffic and external engagement unknown",
      "expectedValue": "Partner/resource click-through rates"
    }
  ],
  "nextSteps": [
    "Invoke gtm-dom-standardization to clean up DOM identifiers",
    "Invoke gtm-strategy to plan tracking implementation based on business goals",
    "Review audit-report.json with stakeholders to prioritize tracking"
  ]
}

阶段 9：收集业务背景

写入 audit-report.json 后，检查项目根目录中是否已存在 gtm-context.md。

If gtm-context.md EXISTS:
  Read it silently - context already captured, skip this phase entirely.

If gtm-context.md does NOT exist:
  Tell the user:
  "A few quick questions to save context for all future skill runs.
   You will not be asked these again."

  Ask these 4 questions (all at once, not one by one):

  1. What type of site or product is this?
     a) Ecommerce (selling products)
     b) SaaS (subscription software)
     c) B2B / lead generation (services, professional, enterprise)
     d) Media / content / publishing
     e) Other (describe briefly)

  2. What are the 1-3 primary conversion goals?
     Examples: trial signups, demo requests, purchases, downloads, contact forms

  3. Which ad platforms are active or planned?
     (Select all that apply: Google Ads, Meta, LinkedIn, TikTok, none, other)

  4. Is server-side tracking (sGTM) in scope?
     a) Yes, already using it
     b) Yes, planning it
     c) Not sure yet
     d) No

  Then write gtm-context.md to the project root:

# GTM Project Context

Generated by gtm-analytics-audit on [date]. Read automatically by all GTM skills.

## Site
- **Type**: [ecommerce / SaaS / B2B lead gen / media / other]
- **Platform**: [framework detected from audit - e.g. Next.js 16, React, Shopify]

## Business Goals
- **Primary conversions**: [listed goals]
- **Ad platforms**: [active or planned platforms]

## Server-Side Tracking
- **In scope**: [yes / planned / not sure / no]

## Notes
[any extra context the user added]

Confirm to user:
"gtm-context.md saved. All GTM skills will read this automatically - no need to answer these questions again."

输出格式

按以下结构向用户呈现发现：

=== GTM Analytics Audit Complete ===

Framework: Next.js 16.1.6 (App Router)
Files Scanned: 47 files
Components Analyzed: 23 components

--- Summary ---
Total Clickable Elements: 47
✓ With Tracking: 15 (31.9%)
✗ Without Tracking: 32 (68.1%)

--- Element Breakdown ---
CTAs: 12 total (4 tracked, 8 untracked)
Navigation: 8 total (2 tracked, 6 untracked)
Forms: 3 total (0 tracked, 3 untracked)
Outbound Links: 5 total (1 tracked, 4 untracked)
Media: 2 total (0 tracked, 2 untracked)

--- Key Issues ---
⚠ 23 elements with generic/missing identifiers
⚠ 8 high-priority CTAs without tracking
⚠ 3 forms without tracking
⚠ Inconsistent tracking patterns

--- Existing Tracking ---
✓ Google Tag Manager detected
✓ 15 dataLayer.push() calls found
△ Coverage: 31.9% of clickable elements

--- Recommendations ---

P0 (Critical):
1. Standardize DOM identifiers across 47 elements
   → Invoke gtm-dom-standardization skill
2. Implement tracking on 12 CTAs
   → Critical for conversion funnel visibility

P1 (Important):
3. Add form tracking (3 forms)
   → Capture lead generation and form abandonment

P2 (Nice-to-have):
4. Track outbound links (5 links)
   → Measure partner/resource engagement

--- Next Steps ---
✓ Audit report saved to: audit-report.json
→ Next: Invoke gtm-dom-standardization to prepare DOM for tracking
→ Then: Invoke gtm-strategy to plan tracking implementation

Ready to standardize your DOM? Invoke gtm-dom-standardization skill.

重要指南

资深工程师思维

• 全面而高效：全面扫描，但清晰总结
• 找出根本原因：不要只报告“缺少跟踪”，还要解释原因（没有 ID、类名过于通用等）
• 提供背景信息：解释每项发现的业务影响
• 系统化思考：系统地分类并确定优先级

针对框架的注意事项

Next.js App Router：

• 客户端组件需要 'use client' 指令才能进行跟踪
• 服务端组件不能直接使用 onClick

React：

• 事件处理程序应包含跟踪调用
• Hook（useState、useEffect）可能会影响跟踪时机

Vue：

• Composition API 与 Options API 会影响事件绑定
• 模板语法与 React 不同

分类逻辑

对难以分类的元素使用以下判断树：

“了解更多”按钮：

• 如果会跳转到产品演示 → CTA
• 如果会导航到信息页面 → 导航
• 默认：CTA（假设其意图是促成转化）

“联系我们”链接：

• 位于导航菜单中 → 导航
• 作为醒目的按钮 → CTA
• 位于页脚中 → 导航

视频播放器：

• 自动播放的背景视频 → 媒体
• 产品演示视频 → 演示 + 媒体

搜索输入框：

• 页眉搜索 → 表单 + 导航
• 内容筛选器 → 表单

避免过度设计

• 不要建议跟踪每一个元素
• 专注于对业务至关重要的交互
• 忽略装饰性或冗余元素
• 根据转化影响确定优先级

参考文件

• references/naming-conventions.md - 分析 ID/类命名标准（用户询问命名时加载）
• examples/sample.md - 展示预期格式和 audit-report.json 结构的审计输出示例

常见问题

问：应该跟踪每个按钮吗？
答：不应该。重点关注对转化至关重要的 CTA、表单和导航。跳过冗余或装饰性元素。

问：如何对难以分类的元素进行分类？
答：根据业务意图判断：它是促成转化（CTA），还是用于导航（导航）？如果不确定，默认归为 CTA。

问：如果代码库完全没有跟踪怎么办？
答：这很常见！重点找出机会，并建议从 P0 元素（CTA、表单）开始。

问：应该扫描 node_modules 吗？
答：不应该。只扫描用户代码（app/、components/、pages/、src/）。忽略 node_modules 和构建目录。