Nuxt Google 标签

Google 标签与 Nuxt 集成，支持 Google Analytics 4、Google Ads 及更多。

特性

🌻 零依赖，除了 Google 的 gtag.js
🛍️ 使用 Google Analytics 4、Google Ads 和其他产品
🛎️ 支持 Google Consent Mode 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 进行初始化。

!NOTE 确保启用增强型衡量功能，以允许 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。

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

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

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

多个 Google 标签

如果您想将数据发送到多个目标位置，您可以在 tags 模块选项的 Nuxt 配置中添加多个 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 键。

!TIP 遵循 Google Consent Mode v2 规范。

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

以下示例将多个 Consent Mode 参数默认设置为拒绝

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` 脚本

为了比 Consent Mode 获得更多控制权，您可以延迟加载 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>

多租户支持

您甚至可以将 Google 标签 ID 留在 Nuxt 配置中为空，并在应用程序中稍后动态设置它，方法是将您的 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`	Source	`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 命令。

!NOTE 由于 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')
}

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

类型声明

function initialize(id?: string): void

`disableAnalytics`

在某些情况下，可能需要禁用 Google Analytics，而无需删除 Google 标签。例如，您可能希望为用户提供选择退出跟踪的选项。

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`

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

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

!NOTE 此组合式函数支持 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 为其 logo 像素艺术作品。
Junyoung Choi 和 Lucas Akira Uehara 为他们的 Google gtag.js API 类型定义