Nuxt Google Tag

Google Tag 与 Nuxt 的集成，支持 Google Analytics 4、Google Ads 等。

功能特性

🌻 除 Google 的 gtag.js 外，零依赖
🛍️ 使用 Google Analytics 4、Google Ads 和其他产品
🛎️ 支持 Google 同意模式 v2
🤝 手动初始化 Google 代码
🔢 支持多个代码 ID
📯 使用组合式函数跟踪事件
🏷️ 完全类型化的 gtag.js API
🦾 支持 SSR

设置

npx nuxi@latest module add gtag

基本用法

将 nuxt-gtag 添加到 Nuxt 配置的 modules 部分，并提供您的 Google 代码 ID（对于多个代码 ID，请参见下文）。

export default defineNuxtConfig({
  modules: ['nuxt-gtag'],

  gtag: {
    id: 'G-XXXXXXXXXX'
  }
})

完成！当 Nuxt 应用程序启动时，gtag.js 脚本将在客户端加载并使用您的 Google 代码 ID 初始化。

!注意确保启用增强型衡量功能，以允许 gtag.js 根据 Nuxt 中的浏览器历史记录事件自动跟踪页面更改。
要启用此功能
转到 GA4 报告视图，然后单击“管理”
在“属性”列下选择“数据流”。
单击您的网站数据流。
接下来，展开“增强型衡量”开关按钮。
确保启用“基于浏览器历史记录事件的页面更改”开关按钮。

配置

所有支持的模块选项都可以使用 Nuxt 配置中的 gtag 键进行配置。以下是一些您可以设置的选项示例

export default defineNuxtConfig({
  modules: ['nuxt-gtag'],

  gtag: {
    // Your primary Google tag ID
    id: 'G-XXXXXXXXXX',
    // Additional configuration for this tag ID
    config: {
      page_title: 'My Custom Page Title'
    },
  }
})

模块的条件启用/禁用

您可能希望在某些环境（例如开发或暂存）中禁用 Google 代码模块。为此，请将 enabled 选项设置为 false。

!注意当模块被禁用时，仍然可以导入像 useGtag 和 useTrackEvent 这样的组合式函数。在这种情况下，这些函数将被替换为 no-op，以避免类型和逻辑错误。

export default defineNuxtConfig({
  modules: ['nuxt-gtag'],

  gtag: {
    enabled: process.env.NODE_ENV === 'production',
    id: 'G-XXXXXXXXXX'
  }
})

多个 Google 代码

如果您想将数据发送到多个目标位置，您可以在 Nuxt 配置的 tags 模块选项中添加多个 Google 代码 ID。将字符串（单个代码 ID）或对象（带有其他配置的代码 ID）传递给 tags 数组。

以下示例展示了如何加载连接到 Floodlight 目标的第二个 Google 代码

export default defineNuxtConfig({
  modules: ['nuxt-gtag'],

  gtag: {
    tags: [
      // Google Ads and GA4, with additional configuration
      {
        id: 'G-XXXXXXXXXX',
        config: {
          page_title: 'My Custom Page Title'
        }
      },
      // Second Google tag ID for Floodlight
      'DC-ZZZZZZZZZZ'
    ]
  }
})

运行时配置

您可以在项目的 .env 文件中设置所需的选项，而无需在 Nuxt 配置中硬编码您的 Google 代码 ID，通过在运行时匹配环境变量来利用自动替换的公共运行时配置值。

# Overwrites the `gtag.id` module option
NUXT_PUBLIC_GTAG_ID=G-XXXXXXXXXX

通过此设置，如果您只想设置 Google 代码 ID，则可以省略 Nuxt 配置中的 gtag 键。

!提示遵循 Google 同意模式 v2 规范。

为您正在使用的每种同意类型设置默认值。默认情况下，未设置任何同意模式值。

以下示例将多个同意模式参数默认设置为拒绝

export default defineNuxtConfig({
  modules: ['nuxt-gtag'],

  gtag: {
    id: 'G-XXXXXXXXXX',
    initCommands: [
      // Setup up consent mode
      ['consent', 'default', {
        ad_user_data: 'denied',
        ad_personalization: 'denied',
        ad_storage: 'denied',
        analytics_storage: 'denied',
        wait_for_update: 500,
      }]
    ]
  }
})

在用户表示其同意选择后，将相关参数更新为 granted

function allConsentGranted() {
  const { gtag } = useGtag()
  gtag('consent', 'update', {
    ad_user_data: 'granted',
    ad_personalization: 'granted',
    ad_storage: 'granted',
    analytics_storage: 'granted'
  })
}

function consentGrantedAdStorage() {
  const { gtag } = useGtag()
  gtag('consent', 'update', {
    ad_storage: 'granted'
  })
}

// Invoke the consent function when a user interacts with your banner
consentGrantedAdStorage() // Or `allConsentGranted()`

手动加载 `gtag.js` 脚本

为了比同意模式更精细的控制，您可以延迟加载 gtag.js 脚本，直到用户同意您的隐私政策。将 initMode 选项设置为 manual，以防止加载 gtag.js 脚本，直到您手动初始化它。

export default defineNuxtConfig({
  modules: ['nuxt-gtag'],

  gtag: {
    initMode: 'manual',
    id: 'G-XXXXXXXXXX'
  }
})

要手动加载 Google 代码脚本，即在用户接受您的隐私政策后，您可以使用可从 useGtag 解构的 initialize 方法

<script setup lang="ts">
const { gtag, initialize } = useGtag()
</script>

<template>
  <button @click="initialize()">
    Grant Consent
  </button>
</template>

多租户支持

您甚至可以在 Nuxt 配置中将 Google 代码 ID 留空，并在应用程序中稍后通过将 ID 作为第一个参数传递给 initialize 来动态设置它。如果您想为每个用户使用自定义 ID 或您的应用管理多个租户，这特别有用。

const { gtag, initialize } = useGtag()

function acceptTracking() {
  initialize('G-XXXXXXXXXX')
  // Optionally, track the current page view
  // useTrackEvent('page_view')
}

模块选项

选项	类型	默认值	描述
`enabled`	`boolean`	`true`	是否为当前环境启用 Google 代码模块。
`initMode`	`string`	`auto`	是否在页面加载后立即初始化 Google 代码脚本。
`id`	`string`	`undefined`	要初始化的 Google 代码 ID。
`initCommands`	请参见 `GoogleTagOptions` 的 `initCommands`	`[]`	在初始化 Google 代码 ID 时要执行的命令。
`config`	请参见 `GoogleTagOptions` 的 `config`	`{}`	要在初始化时传递给 `gtag.js` 的配置参数。
`tags`	`string[] \| GoogleTagOptions[]`	`[]`	要初始化的多个 Google 代码 ID，用于将数据发送到不同的目标位置。
`loadingStrategy`	`'async' \| 'defer'`	`'defer'`	用于 `gtag.js` 脚本的加载策略。
`url`	`string`	源	`gtag.js` 脚本的 URL。使用此选项从自定义 URL 加载脚本。

组合式函数

与 Nuxt 3 生态系统中的其他组合式函数一样，它们是自动导入的，可以在您应用程序的组件中使用。

`useGtag`

SSR 安全的 useGtag 组合式函数提供对以下内容的访问：

gtag.js 实例
initialize 方法
disableAnalytics 方法
enableAnalytics 方法

它可以按如下方式使用

// Each method is destructurable from the composable and can be
// used on the server and client-side
const { gtag, initialize, disableAnalytics, enableAnalytics } = useGtag()

类型声明

function useGtag(): {
  gtag: Gtag
  initialize: (id?: string) => void
  disableAnalytics: (id?: string) => void
  enableAnalytics: (id?: string) => void
}

`gtag`

gtag 函数是 gtag.js 实例的主要接口，可用于运行每个 gtag.js 命令。

!注意由于 gtag.js 实例仅在客户端可用，因此在服务器上执行的任何 gtag() 调用都不会有任何效果。

示例

以下事件命令触发带有两个参数的 screen_view 事件：app_name 和 screen_name。

const { gtag } = useGtag()

// SSR-ready
gtag('event', 'screen_view', {
  app_name: 'My App',
  screen_name: 'Home'
})

类型声明

interface GtagCommands {
  config: [targetId: string, config?: ControlParams | EventParams | ConfigParams | CustomParams]
  set: [targetId: string, config: CustomParams | boolean | string] | [config: CustomParams]
  js: [config: Date]
  event: [eventName: EventNames | (string & {}), eventParams?: ControlParams | EventParams | CustomParams]
  get: [
      targetId: string,
      fieldName: FieldNames | string,
      callback?: (field?: string | CustomParams) => any,
  ]
  consent: [consentArg: ConsentArg | (string & {}), consentParams: ConsentParams]
}

const gtag: {
  <Command extends keyof GtagCommands>(command: Command, ...args: GtagCommands[Command]): void
}

`initialize`

如果您想手动管理 Google 代码脚本的初始化（例如，为了符合 GDPR），您可以使用 initialize 方法在用户接受您的隐私政策后将 gtag.js 脚本注入到文档的头部。确保在 Nuxt 模块中将 enabled 设置为 false，才能使其正常工作。

该函数接受一个可选 ID，以防您想初始化一个自定义 Google 代码 ID，该 ID 未在模块选项中设置。

示例

const { initialize } = useGtag()

// Load the `gtag.js` script and initialize all tag IDs from the module options
function acceptTracking() {
  initialize()
  // Optionally, track the current page view
  // useTrackEvent('page_view')
}

!提示尽管此方法是 SSR 安全的，但 gtag.js 脚本仅在客户端加载。请确保在客户端运行此方法。

类型声明

function initialize(id?: string): void

`disableAnalytics`

在某些情况下，可能需要在不删除 Google 代码的情况下禁用 Google Analytics。例如，您可能想为用户提供退出跟踪的选项。

gtag.js 库包含一个 window 属性，该属性切换 gtag.js 以禁止将数据发送到 Google Analytics。当 Google Analytics 尝试设置 Cookie 或将数据发送回 Google Analytics 服务器时，会检查此属性以确定是否允许该操作。

示例

const { disableAnalytics } = useGtag()

disableAnalytics()

类型声明

function disableAnalytics(id?: string): void

`enableAnalytics`

enableAnalytics 方法是 disableAnalytics 的对应方法，可用于在禁用 Google Analytics 后重新启用它。

示例

const { enableAnalytics } = useGtag()

enableAnalytics()

类型声明

function enableAnalytics(id?: string): void

`useTrackEvent`

通过传递以下参数来跟踪您定义的目标

推荐或自定义事件的名称。
提供有关事件的其他信息的参数集合（可选）。

!注意此组合式函数是 SSR 安全的。但是由于 gtag.js 实例仅在客户端可用，因此在服务器上执行组合式函数将不会有任何效果。

示例

例如，以下是一个名为 login 的事件，带有一个参数 method

// Tracks the `login` event
useTrackEvent('login', {
  method: 'Google'
})

类型声明

function useTrackEvent(
  eventName: EventNames | (string & {}),
  eventParams?: ControlParams | EventParams | CustomParams
): void

💻 开发

克隆此存储库
使用 corepack enable 启用 Corepack
使用 pnpm install 安装依赖项
运行 pnpm run dev:prepare
使用 pnpm run dev 启动开发服务器

迁移

v2.x 到 v3.x

在 v2.x 及更早版本中，enabled 选项用于控制 Google 代码脚本的手动初始化。此选项在 v3.x 中已替换为 initMode。要迁移您的配置，请将 initMode 选项设置为 manual

export default defineNuxtConfig({
  modules: ['nuxt-gtag'],

  gtag: {
-    enabled: false,
+    initMode: 'manual',
    id: 'GX-XXXXXXXXXX'
  }
})

enabled 选项在 v3.x 中仍然可用，但现在用于为当前环境禁用 Google 代码模块。如果您想在开发或暂存环境中禁用该模块，这将非常有用

export default defineNuxtConfig({
  modules: ['nuxt-gtag'],

  gtag: {
    enabled: process.env.NODE_ENV === 'production',
    id: 'G-XXXXXXXXXX'
  }
})

鸣谢

Maronbeere 的徽标像素艺术。
Junyoung Choi 和 Lucas Akira Uehara 的 Google gtag.js API 类型定义