gatsby-plugin-google-gtag：在 Gatsby 站点中集成 Google Global Site Tag 的完整实践

gatsby-plugin-google-gtag在 Gatsby 站点中集成 Google Global Site Tag 的完整实践【免费下载链接】gatsbyReact-based framework with performance, scalability, and security built in.项目地址: https://gitcode.com/gh_mirrors/ga/gatsby本篇以 Gatsby 仓库中的 gatsby-plugin-google-gtag 插件文档 为核心完整覆盖该插件的安装、配置参数trackingIds、gtagConfig、pluginConfig、自定义事件与OutboundLink组件的使用方式并结合仓库源码剖析其在 SSR 阶段注入追踪脚本、在浏览器端发送page_view事件的具体实现链路帮助你在 Gatsby 5 站点中正确接入 GA4 / Google Ads 等 Google 标签体系。什么是 Global Site Taggtag.jsGoogle 的 global site taggtag.js是一个 JavaScript 标签框架与 API允许你将事件数据发送到 Google Analytics、Google Ads、Campaign Manager、Display Video 360 以及 Search Ads 360。它的设计目标是合并多个 Google 标签系统因此可以取代较旧的 analytics.js对应 Gatsby 生态中的gatsby-plugin-google-analytics插件。gatsby-plugin-google-gtag的定位就是在 Gatsby 站点中方便地注入 gtag.js。相比手动复制粘贴 Google 给出的代码片段该插件额外解决了 SPA 场景下的几个关键问题在每次 Gatsby 路由变化时自动发送pageview事件传统script标签只会在首次加载时发一次通过exclude选项按 glob 表达式排除某些路径通过respectDNT选项尊重浏览器的 Do Not Track 设置通过OutboundLink组件便捷地追踪出站链接点击。重要前提该插件仅在 production 模式下工作。要验证 Global Site Tag 是否正确安装并触发事件需要运行gatsby build gatsby serve。这一点在源码中得到直接印证——gatsby-ssr.js 的onRenderBody开头即有守卫if (process.env.NODE_ENV ! production process.env.NODE_ENV ! test) return null即非 production且非测试环境下插件在渲染阶段直接不做任何注入。安装npm install gatsby-plugin-google-gtag插件的 package.json 中声明了对gatsby ^5.0.0的 peer 依赖运行环境要求 Node18.0.0 26。基本配置trackingIds是必填选项缺失时插件无法正常工作。完整的配置示例如下module.exports { plugins: [ { resolve: gatsby-plugin-google-gtag, options: { // You can add multiple tracking ids and a pageview event will be fired for all of them. trackingIds: [ GA-TRACKING_ID, // Google Analytics / GA AW-CONVERSION_ID, // Google Ads / Adwords / AW DC-FLOODIGHT_ID, // Marketing Platform advertising products (Display Video 360, Search Ads 360, and Campaign Manager) ], // This object gets passed directly to the gtag config command // This config will be shared across all trackingIds gtagConfig: { optimize_id: OPT_CONTAINER_ID, anonymize_ip: true, cookie_expires: 0, }, // This object is used for configuration specific to this plugins specific configuration pluginConfig: { // Puts tracking script in the head instead of the body head: false, // Setting this parameter is also optional respectDNT: true, // Avoids sending pageview hits from custom paths exclude: [/preview/**, /do-not-track/me/too/], // Defaults to https://www.googletagmanager.com origin: YOUR_SELF_HOSTED_ORIGIN, // Delays processing pageview events on route update (in milliseconds) delayOnRouteUpdate: 0, }, }, }, ], }选项的合法性由 gatsby-node.js 中导出的pluginOptionsSchema通过 Joi 在插件加载时校验默认值与约束如下源码中的定义选项类型默认值说明trackingIdsstring[]无required追踪 ID 列表没有它们不会生成追踪代码gtagConfigobject{}直接透传给gtag(config, ...)命令gtagConfig.anonymize_ipbooleanfalse启用 IP 匿名化_anonymizeIPpluginConfig.headbooleanfalse将追踪脚本放入head而非bodypluginConfig.respectDNTbooleanfalse对开启 Do Not Track 的访客完全不加载 gtagpluginConfig.excludestring[][]以 glob 表达式排除的路径pluginConfig.originstringhttps://www.googletagmanager.com自托管脚本的 originpluginConfig.delayOnRouteUpdatenumber0路由更新后处理 pageview 事件的延迟毫秒仓库中的 schema 测试 明确验证了错误配置会产生的报错信息例如缺失trackingIds时报trackingIds is required、pluginConfig.origin传数字时报pluginConfig.origin must be a string等。gtagConfig使用了unknown(true)因此除了显式声明的optimize_id与anonymize_ip其余键都会原样透传。选项详解gtagConfig.anonymize_ip某些国家例如德国要求对 Google Site Tag 使用_anonymizeIP函数否则不允许使用。开启该选项后插件会注入如下代码块对应 gatsby-ssr.js 中的内联脚本生成逻辑function gaOptout() { ;(document.cookie disableStr true; expiresThu, 31 Dec 2099 23:59:59 UTC;path/), (window[disableStr] !0) } var gaProperty UA-XXXXXXXX-X, disableStr ga-disable- gaProperty document.cookie.indexOf(disableStr true) -1 (window[disableStr] !0)从源码看gaProperty取的是trackingIds数组中的第一个IDga-disable-IDcookie 会被检查并在页面加载时同步到window标志位。如果希望访客能够主动设置 Opt-Out-Cookie即不再被追踪可以在站点页脚/法律声明等位置放置一个链接a hrefjavascript:gaOptout();Deactivate Google Tracking/agtagConfig.optimize_id如果需要使用 Google Optimize 做 A/B 测试可以添加这个可选的 Optimize 容器 ID以便 Google Optimize 为你的站点加载正确的测试参数。其他gtagConfig选项gtagConfig会原样传入gtag 的 config 命令因此它支持的一切字段都可以使用例如gtagConfig.cookie_name、gtagConfig.sample_rate。如果你正在从 analytics.js 插件迁移过来意味着所有 Create Only Fields 都应改为 snake_case 命名如cookieName→cookie_name。pluginConfig.respectDNT启用该可选项后开启了 Do Not Track 的访客将完全不会加载 Google Global Site Tag。虽然使用 Global Site Tag 不一定构成法律意义上的 追踪但为更重视隐私的用户群体服务时这是一个有价值的开关。从实现看gatsby-ssr.js 会在整个dataLayer/gtag初始化代码外层包裹一个条件判断if(!(navigator.doNotTrack 1 || window.doNotTrack 1)) { window.dataLayer window.dataLayer || []; function gtag(){dataLayer.push(arguments);} gtag(js, new Date()); // ... gtag(config, ...) 对每个 trackingId 执行 }当respectDNT为false默认时该条件渲染为if(true)即不做任何 DNT 检查。对应的测试用例 分别断言了默认情况下输出 HTML 中不含 DNT 字符串、开启后包含该字符串。pluginConfig.exclude如果需要将某些路径排除在追踪体系之外可以把一个或多个路径以glob 表达式的形式加入该可选数组例如[/preview/**, /do-not-track/me/too/]。底层实现分两步SSR 阶段gatsby-ssr.js使用minimatch插件的运行时依赖之一将每个 glob 转换为正则并写入页面内联脚本window.excludeGtagPaths[/^\S*.../, ...]浏览器阶段gatsby-browser.js路由更新时逐一用这些正则测试location.pathname命中任一正则则跳过本次page_view事件。pluginConfig.origin默认脚本来源为https://www.googletagmanager.com。如果你自托管了 gtag 脚本可以替换为自有 origin。从 SSR 源码 可以看到origin同时作用于两处head中注入的link relpreconnect与link reldns-prefetchLighthouse 建议对 Google Tag Manager 域名做预连接以降低脚本加载延迟实际script async src${origin}/gtag/js?id${firstTrackingId}的src。相关测试 验证了默认 origin 与自定义 origin 两种情况下上述三处均使用同一 origin。pluginConfig.delayOnRouteUpdate如果需要延迟处理路由更新时的 pageview 事件例如等待gatsby-plugin-transition-link的页面过渡动画完成该选项会在生成 pageview 事件之前加入指定的毫秒级延迟。插件在 Gatsby 生命周期中的工作方式SSR 阶段onRenderBody注入脚本gatsby-ssr.js 导出的onRenderBody是插件的核心。它做了以下几件事preconnect / dns-prefetch为 origin 域注入head链接优化脚本加载性能关闭 gtag 内置的初始 pageview在透传的gtagConfig中强制设置gtagConfig.send_page_view falseL25。这是为了避免首次加载时由config命令触发一次、而 SPA 路由又由浏览器端再发一次从而造成重复的 pageview 事件按head选项决定脚本位置pluginConfig.head为真时通过setHeadComponents注入head否则通过setPostBodyComponents注入到body之后L40-L42生成内联配置脚本对每个trackingId逐条生成gtag(config, id, {...})命令gtagConfig经JSON.stringify序列化后内嵌。最终产出的 HTML 结构等价于script async srchttps://www.googletagmanager.com/gtag/js?idGA-TRACKING_ID/script script window.excludeGtagPaths[/* 由 exclude 生成的正则 */]; /* 若 anonymize_ip: true此处还有 gaOptout 代码块 */ if(true /* respectDNT 为 true 时替换为 DNT 判断 */) { window.dataLayer window.dataLayer || []; function gtag(){dataLayer.push(arguments);} gtag(js, new Date()); gtag(config, GA-TRACKING_ID, {send_page_view:false, ...}); gtag(config, AW-CONVERSION_ID, {send_page_view:false, ...}); } /script浏览器阶段onRouteUpdate发送 pageviewgatsby-browser.js 监听 Gatsby 的onRouteUpdateAPIexports.onRouteUpdate ({ location }, pluginOptions {}) { if (process.env.NODE_ENV ! production || typeof gtag ! function) { return null } // ... 排除路径检查 const sendPageView () { const pagePath location ? location.pathname location.search location.hash : undefined window.gtag(event, page_view, { page_path: pagePath }) } // 双层 requestAnimationFrame setTimeout(delayOnRouteUpdate) }几个值得注意的实现细节事件携带完整的page_pathpathname search hash保证带 query/锚点的导航也被正确记录发送前会用window.excludeGtagPaths正则测试当前pathname命中即返回sendPageView被包裹在两层requestAnimationFrame之后再叠加setTimeout(delayOnRouteUpdate)——源码注释说明这是为了确保react-helmet等对 document 的修改已经完成在不支持requestAnimationFrame的环境下退化为固定的 32ms 延迟模拟两次 rAF再加配置延迟。自定义事件Custom Events该插件会自动为所有trackingIds中给出的产品在每次 Gatsby 路由变化时发送pageview事件。如需触发自定义事件可以直接访问全局的window.gtag向所有产品发送window.gtag(event, click, { ...data })或者用send_to指定特定产品window.gtag(event, click, { send_to: AW-CONVERSION_ID, ...data })无论哪种方式都要记得对 SSR 做防护typeof window ! undefined window.gtag(event, click, { ...data })OutboundLink组件为了简化出站链接点击的追踪插件提供了一个OutboundLink组件实现见 src/index.js类型定义见 index.d.ts用法与a元素一致import React from react import { OutboundLink } from gatsby-plugin-google-gtag export default () ( div OutboundLink hrefhttps://www.gatsbyjs.com/plugins/gatsby-plugin-google-gtag/ Visit the Google Global Site Tag plugin page! /OutboundLink /div )从源码实现看它比文档描述做了更多细节处理先调用用户传入的onClick如果提供随后发送event_category: outbound、event_label: props.href的click事件重定向判定只有左键单击、且未附带altKey/ctrlKey/metaKey/shiftKey、defaultPrevented未设置、target为_self或未指定时才会由组件接管跳转中键点击、target_blank等场景直接放行不发送 beacon、不阻止默认行为可接管跳转的场景下使用transport_type: beacon并通过event_callback在事件上报完成后才执行document.location href尽量降低跳转导致事件丢失的概率若当前环境没有window.gtag如未通过校验或 DNT 被排除则退化为直接跳转。组件以React.forwardRef实现并透传全部a属性因此className、aria-*等属性均可正常使用。验证与排错由于插件仅在 production 模式生效推荐的验证流程是gatsby build gatsby serve然后在浏览器中打开页面通过 Google 官方的 Tag Assistant 或 GA4 的 DebugView 确认事件是否上报。如果事件没有触发可以按以下顺序排查trackingIds是否已配置且格式正确Joi schema 缺失必填项会在构建时直接报错是否误在gatsby develop下测试开发模式下 SSR 注入与浏览器端onRouteUpdate均被守卫短路当前路径是否命中pluginConfig.exclude的 glob 表达式或开启了respectDNT而浏览器启用了 DNT自托管origin是否可正常访问/gtag/js路径。小结gatsby-plugin-google-gtag通过三个 Gatsby API 协作完成完整链路gatsby-ssr.js 在onRenderBody中注入 preconnect、gtag 加载脚本与逐 ID 的 config 命令并强制send_page_view: false防止首次加载重复计数gatsby-browser.js 在onRouteUpdate中处理排除路径、延迟与 rAF 时序后发送page_viewgatsby-node.js 用 Joi schema 保证选项合法且提供合理默认值而 src/index.js 提供了带跳转时序优化的OutboundLink组件。配合本文完整的参数说明与源码级解释你可以放心地将 GA4、Google AdsAW-及 Marketing PlatformDC-等产品接入自己的 Gatsby 站点。【免费下载链接】gatsbyReact-based framework with performance, scalability, and security built in.项目地址: https://gitcode.com/gh_mirrors/ga/gatsby创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考