Nuxt Google 标签

用于 Nuxt 的 Google 标签集成，支持 Google Analytics 4、Google Ads 等。

功能

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

设置

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 等组合式函数仍然可以导入。在这种情况下，这些函数将被替换为无操作函数，以避免类型和逻辑错误。

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'
    ]
  }
})

运行时配置

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

# 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 标签脚本，例如在用户接受您的隐私政策后，您可以使用 initialize 方法从 useGtag 中解构

<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`	`布尔值`	`true`	是否为当前环境启用 Google 标签模块。
`initMode`	`字符串`	`auto`	页面加载后是否立即初始化 Google 标签脚本。
`id`	`字符串`	`未定义`	要初始化的 Google 标签 ID。
`initCommands`	参见 `GoogleTagOptions` 的 `initCommands`	`[]`	初始化 Google 标签 ID 时要执行的命令。
`config`	参见 `GoogleTagOptions` 的 `config`	`{}`	初始化时要传递给 `gtag.js` 的配置参数。
`tags`	`string[] \| GoogleTagOptions[]`	`[]`	要初始化的多个 Google 标签 ID，用于向不同的目标发送数据。
`loadingStrategy`	`'async' \| 'defer'`	`'defer'`	用于 `gtag.js` 脚本的加载策略。
`url`	`字符串`	来源	指向 `gtag.js` 脚本的 URL。使用此选项从自定义 URL 加载脚本。

组合式函数

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

`useGtag`

服务器端渲染安全的 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。

如果要初始化未在模块选项中设置的自定义 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')
}

!提示虽然此方法是服务器端渲染安全的，但 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`

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

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

!注意此组合式函数支持服务器端渲染。但由于 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 类型定义