zero-cost-tracking

用途

zero-cost-tracking 用于为 Astro.js 构建的线索收集站点提供转化追踪能力，基于 @leadgen/conversion-tracking 包，将 Google Tag Manager、GA4、Google Ads 增强型转化与 Meta CAPI 整合在一起。适用场景包括：需要配合 Google Ads + GA4 + Meta 追踪的线索站点、计算器/联系表单/回电类转化、需要为 Safari 与 iOS 提供增强型转化、需要首次与末次触点 UTM 归因，以及需要同意感知（GDPR 合规）的追踪。

主要能力

方案支持以下事件追踪：phone_click、quote_request、callback_request、contact_form、calculator_start、calculator_step、calculator_option、form_abandon。其中转化类事件（quote_request、callback_request、contact_form）同时上报 GA4、Google Ads、Meta 与 Sheets，并携带归因数据；phone_click 上报 GA4、Google Ads、Meta 但不含归因；计算器与表单流失事件仅上报 GA4。

架构上分为两部分：Cloudflare 边缘层包含 Google Tag Gateway（代理 GTM，绕过广告拦截器）与 Zaraz（服务端 Meta CAPI）；浏览器层通过 dataLayer.push() 流向 GTM 再到 GA4 与 Google Ads，zaraz.track() 流向 Meta CAPI，fetch('/api/lead') 发送至 Sheets。

关键行为方面：会话使用 localStorage 加上 30 分钟不活跃超时，跨标签页一致；电话点击每会话去重一次，页面刷新可再次触发；归因中首次触点不被覆盖，末次触点持续更新；View Transitions 导航时自动重新捕获参数。

使用方式

安装：npm install @leadgen/conversion-tracking

在 astro.config.mjs 中注册集成：

import { defineConfig } from 'astro/config';
import tracking from '@leadgen/conversion-tracking';

export default defineConfig({
  integrations: [
    tracking({
      gtmId: 'GTM-XXXXXXX',     // Required
      currency: 'GBP',          // Optional (default: GBP)
      sessionTimeoutMinutes: 30, // Optional (default: 30)
      debug: false,             // Optional
    })
  ]
});

该集成会自动在每一页注入 GTM 并初始化追踪。表单转化使用 trackConversion 与 buildSheetsPayload，并从 @leadgen/conversion-tracking/client 导入。电话链接使用 PhoneLink.astro 组件。计算器事件使用 pushCalculatorStart、pushCalculatorStep、pushCalculatorOption；表单流失使用 pushFormAbandon。

Sheets Payload 由 buildSheetsPayload() 返回，字段包含 lead_id、event_type、submitted_at、tracking_version、session_id、consent_state、source_type、name/email/phone、value/currency、first_utm_/last_utm_、first_gclid/last_gclid、idempotency_key 等。

GTM 配置需创建数据层变量、User Provided Data（用于增强型转化的 email 与 phone）、自定义事件触发器以及 CookieYes CMP、Conversion Linker、Google Tag、GA4 事件标签、Google Ads 转化标签等。Cloudflare 配置需启用 Google Tag Gateway，并在 Zaraz 中设置 Facebook Pixel 工具，填入 Pixel ID 与 Access Token，开启服务端模式，并将 phone_click、quote_request、callback_request、contact_form 分别映射为 Meta Lead 事件。

适用场景与限制

该方案适合需要将线索转化数据同时上报至多个广告与分析平台的 Astro 站点，尤其是涉及计算器报价、电话点击与表单提交的线索生成业务。使用时有若干核心规则：GTM 是唯一权威，consent.ts 为只读辅助；localStorage 由包内处理 try/catch 以保证 Safari 安全；表单顺序必须为 reportValidity() → preventDefault() → track → redirect；归因仅附加在转化事件上，计算器事件保持最小化；Meta Token 只能放在 Zaraz 中，绝不能出现在代码或环境变量里。禁止事项包括：在代码中写入 Meta Access Token、因追踪失败而阻塞表单提交、在计算器事件上附加归因数据、从 JavaScript 覆盖 GTM 同意设置。

该方案不处理跨域追踪、电商/商品追踪、A/B 测试追踪以及实时仪表盘。相关配套技能包括 crm-integrations（用于 Sheets webhook 与重试队列）与 astro-forms（用于表单验证模式）。

技能介绍

用途

主要能力

使用方式

适用场景与限制