nuxt-gtag

Nuxt 用の Google アナリティクス連携: Google Analytics、Google Ads など

164.5K ダウンロード•354 スター•v4.0.0

johannschopplich

Nuxt Google タグ

Google タグと Nuxt の連携で、Google アナリティクス 4、Google 広告などをサポートします。

機能

🌻 Google の gtag.js 以外の依存関係はゼロ
🛍️ Google Analytics 4、Google 広告、その他のプロダクトを使用
🛎️ Google 同意モード v2 をサポート
🤝 Google タグを手動で初期化
🔢 複数のタグ ID をサポート
📯 Composables でイベントをトラッキング
🏷️ 完全に型付けされた gtag.js API
🦾 SSR対応

セットアップ

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 のようなコンポーザブルはインポート可能です。この場合、型の不一致やロジックエラーを避けるため、関数は no-op に置き換えられます。

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

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

複数の Google タグ

複数の宛先にデータを送信したい場合は、Nuxt 設定の tags モジュールオプションに複数の Google タグ ID を追加できます。tags 配列に文字列（単一のタグ ID）またはオブジェクト（追加設定を含むタグ ID）を渡します。

次の例は、Floodlight の宛先に接続された 2 番目の 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')
}

モジュールオプション

オプション	タイプ	デフォルト	説明
`有効`	`ブール値`	`true`	現在の環境で Google タグモジュールを有効にするかどうか。
`initMode`	`文字列`	`auto`	ページが読み込まれた直後に Google タグスクリプトを初期化するかどうか。
`ID`	`文字列`	`undefined`	初期化する 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`

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() 呼び出しは効果がありません。

例

次のイベントコマンドは、app_name と screen_name の 2 つのパラメータを持つイベント screen_view を発行します。

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

!TIP このメソッドは SSR セーフですが、gtag.js スクリプトはクライアント側でのみ読み込まれます。このメソッドはクライアントで実行するようにしてください。

型宣言

function initialize(id?: string): void

`disableAnalytics`

場合によっては、Google タグを削除せずに Google アナリティクスを無効にする必要があるかもしれません。例えば、ユーザーに追跡のオプトアウトオプションを提供したい場合などです。

gtag.js ライブラリには、window プロパティが含まれており、これが gtag.js が Google アナリティクスにデータを送信するかどうかを切り替えます。Google アナリティクスが Cookie を設定したり、Google アナリティクスサーバーにデータを送信しようとすると、このプロパティがチェックされ、アクションを許可するかどうかが決定されます。

例

const { disableAnalytics } = useGtag()

disableAnalytics()

型宣言

function disableAnalytics(id?: string): void

`enableAnalytics`

enableAnalytics メソッドは disableAnalytics の反対で、無効にされた Google アナリティクスを再度有効にするために使用できます。

例

const { enableAnalytics } = useGtag()

enableAnalytics()

型宣言

function enableAnalytics(id?: string): void

`useTrackEvent`

以下のパラメータを渡して、定義された目標を追跡します。

推奨またはカスタムイベントの名前。
イベントに関する追加情報を提供するパラメータのコレクション（オプション）。

!NOTE このコンポーザブルは SSR 対応です。ただし、gtag.js インスタンスはクライアント側でのみ利用できるため、サーバーでコンポーザブルを実行しても効果はありません。

例

例えば、次の例は、パラメータ method を持つ login というイベントです。

// 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 型定義に感謝します。