nuxt-gtag

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

164.5K 下载•354 星•v4.0.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 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 等可组合项仍然可以导入。在这种情况下，这些函数被替换为无操作，以避免类型和逻辑错误。

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

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

模块选项

选项	类型	默认	描述
`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 脚本注入文档的 head。请确保在 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 的徽标像素艺术。
Junyoung Choi 和 Lucas Akira Uehara 的 Google gtag.js API 类型定义