Nuxt Googleタグ

GoogleタグのNuxt向け連携。 Google Analytics 4、Google広告などをサポートします。

機能

🌻 Googleのgtag.js以外に依存関係なし
🛍️ Google Analytics 4、Google広告、その他の製品を利用可能
🛎️ Google Consent Mode v2をサポート
🤝 Googleタグの手動初期化
🔢 複数のタグIDをサポート
📯 コンポーザブルでイベントを追跡
🏷️ 完全型付けされたgtag.js API
🦾 SSR対応

セットアップ

npx nuxi@latest module add gtag

基本的な使い方

Nuxt設定のmodulesセクションにnuxt-gtagを追加し、GoogleタグIDを設定します（複数のタグIDについては下記参照）。

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

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

完了！ Nuxtアプリケーション起動時に、GoogleタグIDを指定してクライアント側でgtag.jsスクリプトが読み込まれ、初期化されます。

!NOTE Nuxtでのブラウザ履歴イベントに基づくページ変更をgtag.jsが自動的に追跡できるように、拡張計測機能が有効になっていることを確認してください。
この機能を有効にするには
GA4レポートビューに移動し、「管理」をクリックします。
「プロパティ」列の下にある「データストリーム」を選択します。
Webデータストリームをクリックします。
次に、「拡張計測機能」のスイッチボタンを展開します。
「ブラウザ履歴イベントに基づくページ変更」のスイッチボタンが有効になっていることを確認します。

設定

すべてのサポートされているモジュールオプションは、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タグ

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

次の例は、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 Consent Mode 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スクリプトの読み込みを遅らせることができます。gtag.jsスクリプトを手動で初期化するまで読み込まないようにするには、initModeオプションをmanualに設定します。

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を空白のままにして、initializeの最初の引数にIDを渡して、アプリケーションで動的に設定することもできます。これは、ユーザーごとにカスタム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`	`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`	`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()呼び出しは効果がありません。

例

次のイベントコマンドは、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スクリプトをドキュメントのheadに挿入できます。これを機能させるには、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 Analyticsを無効にする必要がある場合があります。たとえば、ユーザーに追跡をオプトアウトするオプションを提供したい場合があります。

gtag.jsライブラリには、gtag.jsがGoogle Analyticsにデータを送信するのを切り替えるwindowプロパティが含まれています。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インスタンスはクライアントでのみ使用できるため、サーバーでコンポーザブルを実行しても効果はありません。

例

たとえば、以下は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。
Google gtag.js API型定義のJunyoung ChoiとLucas Akira Uehara。