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 型別定義