Nuxt Google Tag

Google Tag 與 Nuxt 整合，支援 Google Analytics 4 (分析)、Google Ads (廣告) 等。

特色

🌻 零依賴，除了 Google 的 gtag.js
🛍️ 使用 Google Analytics 4 (分析)、Google Ads (廣告) 和其他產品
🛎️ 支援 Google 同意模式 v2
🤝 手動初始化 Google Tag
🔢 支援多個 Tag ID
📯 使用組合式函式追蹤事件
🏷️ 完整類型定義的 gtag.js API
🦾 支援 SSR

設定

npx nuxi@latest module add gtag

基本用法

將 nuxt-gtag 加入 Nuxt 設定檔的 modules 區段，並提供您的 Google Tag ID（若有多個 Tag ID，請參閱下方）。

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

  gtag: {
    id: 'G-XXXXXXXXXX'
  }
})

完成！當 Nuxt 應用程式啟動時，將會載入 gtag.js 腳本，並使用您的 Google Tag 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 Tag 模組。若要執行此操作，請將 enabled 選項設定為 false。

!NOTE 當模組停用時，仍然可以匯入 useGtag 和 useTrackEvent 等組合式函式。在這種情況下，這些函式會被替換為 no-op，以避免類型和邏輯錯誤。

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

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

多個 Google Tag

如果您想要將資料傳送到多個目的地，您可以在 tags 模組選項中的 Nuxt 設定檔中新增多個 Google Tag ID。將字串（單一 Tag ID）或物件（具有額外設定的 Tag ID）傳遞至 tags 陣列。

以下範例示範如何載入第二個連接到 Floodlight 目標位置的 Google Tag

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 Tag ID，並利用自動替換的公開執行階段設定值，方法是在執行階段比對環境變數。

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

透過此設定，如果您只想設定 Google Tag 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 Tag 腳本，例如在使用者接受您的隱私權政策之後，您可以使用可從 useGtag 解構的 initialize 方法

<script setup lang="ts">
const { gtag, initialize } = useGtag()
</script>

<template>
  <button @click="initialize()">
    Grant Consent
  </button>
</template>

多租戶支援

您甚至可以將 Nuxt 設定檔中的 Google Tag 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 Tag 模組。
`initMode`	`字串`	`auto`	是否在頁面載入後立即初始化 Google Tag 腳本。
`id`	`字串`	`未定義`	要初始化的 Google Tag ID。
`initCommands`	請參閱 `GoogleTagOptions` 的 `initCommands`	`[]`	初始化 Google Tag ID 時要執行的命令。
`config`	請參閱 `GoogleTagOptions` 的 `config`	`{}`	要傳遞給 `gtag.js` 以進行初始化的設定參數。
`tags`	`字串陣列 \| GoogleTagOptions 陣列`	`[]`	要初始化的多個 Google Tag ID，用於將資料傳送到不同的目的地。
`loadingStrategy`	`'async' \| 'defer'`	`'defer'`	用於 `gtag.js` 腳本的載入策略。
`url`	`字串`	來源	`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 Tag 腳本的初始化，例如為了符合 GDPR 規範，您可以使用 initialize 方法在使用者接受您的隱私權政策後，將 gtag.js 腳本注入到文件的 head 中。請確保在 Nuxt 模組中將 enabled 設定為 false，這樣才能運作。

此函式接受選用的 ID，以防您想要初始化自訂 Google Tag 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 Tag。例如，您可能想要為使用者提供選擇退出追蹤的選項。

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 Tag 腳本的手動初始化。此選項已在 v3.x 中被 initMode 取代。若要遷移您的設定，請將 initMode 選項設定為 manual

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

  gtag: {
-    enabled: false,
+    initMode: 'manual',
    id: 'GX-XXXXXXXXXX'
  }
})

enabled 選項在 v3.x 中仍然可用，但現在用於停用目前環境的 Google Tag 模組。如果您想要在開發或預備環境中停用模組，這非常有用

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