nuxt-gtag

用于 Nuxt 的 Google Analytics（分析）集成：Google Analytics（分析）、Google Ads 等

173.1K 下载•360 颗星•v4.1.0

johannschopplich

Nuxt Google 标签

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

功能

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

设置

npx nuxt 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 标签模块，例如开发或 staging。为此，请将 enabled 选项设置为 false。

!NOTE 当模块禁用时，仍然可以导入 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'
    ]
  }
})

运行时配置

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

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

通过此设置，如果您只打算设置 Google 标签 ID，则可以省略 Nuxt 配置中的 gtag 键。

!TIP 遵循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')
}

您可以将动态标签 ID 与同意模式结合使用，方法是在配置中设置 initCommands 而不设置静态 id。当您需要在知道要加载哪个租户的标签 ID 之前设置同意默认值时，这很有用

// nuxt.config.ts
export default defineNuxtConfig({
  modules: ['nuxt-gtag'],

  gtag: {
    initMode: 'manual',
    // No static ID needed for multi-tenant apps
    initCommands: [
      ['consent', 'default', {
        analytics_storage: 'denied',
        ad_storage: 'denied',
        ad_user_data: 'denied',
        ad_personalization: 'denied',
        wait_for_update: 500,
      }]
    ]
  }
})

然后，在运行时使用租户特定的 ID 进行初始化。initCommands 将自动应用

const { gtag, initialize } = useGtag()

// Consent defaults are applied when initializing with dynamic ID
initialize('G-TENANT-123')

// Later, after user grants consent
gtag('consent', 'update', {
  analytics_storage: 'granted',
  ad_storage: 'granted',
  ad_user_data: 'granted',
  ad_personalization: 'granted'
})

模块选项

选项	类型	默认	描述
`enabled`	`boolean`	`true`	是否为当前环境启用 Google 标签模块。
`initMode`	`string`	`auto`	页面加载后是否立即初始化 Google 标签脚本。
`ID`	`string`	`未定义`	要初始化的 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 命令。

!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。

示例

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 标签的情况下禁用 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`

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

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

!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 标签模块。如果您想在开发或 staging 环境中禁用该模块，这很有用

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 类型定义