nuxt-gtag

Nuxt Google Tag

Google Tag integration for Nuxt with support for Google Analytics 4, Google Ads and more.

Features

• 🌻 Zero dependencies except Google's gtag.js
• 🛍️ Use Google Analytics 4, Google Ads and other products
• 🛎️ Supports Google Consent Mode v2
• 🤝 Manually initialize a Google tag
• 🔢 Supports multiple tag IDs
• 📯 Track events with composables
• 🏷️ Fully typed gtag.js API
• 🦾 SSR-ready

Setup

npx nuxi@latest module add gtag

Basic Usage

Add nuxt-gtag to the modules section of your Nuxt configuration and provide your Google tag ID (for multiple tag IDs, see below).

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

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

Done! The gtag.js script will be loaded and initialized client-side with your Google tag ID when the Nuxt application starts.

[!NOTE] Ensure that the Enhanced measurement feature is enabled to allow gtag.js to automatically track page changes based on browser history events in Nuxt.

To enable this feature:

1. Go to the GA4 reporting view and click on “Admin”
2. Select “Data Streams” under the “Property” column.
3. Click on your web data stream.
4. Next, expand the switch button “Enhanced measurement”.
5. Ensure the “Page changes based on browser history events” switch button is enabled.

Configuration

All supported module options can be configured using the gtag key in your Nuxt configuration. An example of some of the options you can set:

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

Conditional Enable/Disable of the Module

You may want to disable the Google tag module in certain environments, such as development or staging. To do this, set the enabled option to false.

[!NOTE] Composables like useGtag and useTrackEvent are still importable when the module is disabled. In this case, the functions are replaced with no-ops to avoid type and logic errors.

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

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

Multiple Google Tags

If you want to send data to multiple destinations, you can add more than one Google tag ID to your Nuxt configuration in the tags module option. Pass a string (single tag ID) or an object (tag ID with additional configuration) to the tags array.

The following example shows how to load a second Google tag that is connected to a Floodlight destination:

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

Runtime Config

Instead of hard-coding your Google tag ID in your Nuxt configuration, you can set your desired option in your project's .env file, leveraging automatically replaced public runtime config values by matching environment variables at runtime.

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

With this setup, you can omit the gtag key in your Nuxt configuration if you only intend to set the Google tag ID.

Google Consent Mode

[!TIP] Follows the Google Consent Mode v2 specification.

Set a default value for each consent type you are using. By default, no consent mode values are set.

The following example sets multiple consent mode parameters to denied by default:

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,
      }]
    ]
  }
})

After a user indicates their consent choices, update relevant parameters to 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()`

Manually Load gtag.js Script

For even more control than the consent mode, you can delay the loading of the gtag.js script until the user has granted consent to your privacy policy. Set the initMode option to manual to prevent loading the gtag.js script until you initialize it manually.

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

  gtag: {
    initMode: 'manual',
    id: 'G-XXXXXXXXXX'
  }
})

To manually load the Google tag script, i.e. after the user has accepted your privacy policy, you can use the initialize method destructurable from useGtag:

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

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

Multi-Tenancy Support

You can even leave the Google tag ID in your Nuxt config blank and set it dynamically later in your application by passing your ID as the first argument to initialize. This is especially useful if you want to use a custom ID for each user or if your app manages multiple tenants.

const { gtag, initialize } = useGtag()

function acceptTracking() {
  initialize('G-XXXXXXXXXX')
  // Optionally, track the current page view
  // useTrackEvent('page_view')
}

Module Options

Option	Type	Default	Description
enabled	boolean	true	Whether to enable the Google tag module for the current environment.
initMode	string	auto	Whether to initialize the Google tag script immediately after the page has loaded.
id	string	undefined	The Google tag ID to initialize.
initCommands	See initCommands of GoogleTagOptions	[]	Commands to be executed when the Google tag ID is initialized.
config	See config of GoogleTagOptions	{}	The configuration parameters to be passed to gtag.js on initialization.
tags	string[] | GoogleTagOptions[]	[]	Multiple Google tag IDs to initialize for sending data to different destinations.
loadingStrategy	'async' | 'defer'	'defer'	The loading strategy to be used for the gtag.js script.
url	string	Source	The URL to the gtag.js script. Use this option to load the script from a custom URL.

Composables

As with other composables in the Nuxt 3 ecosystem, they are auto-imported and can be used in your application's components.

useGtag

The SSR-safe useGtag composable provides access to:

• The gtag.js instance
• The initialize method
• The disableAnalytics method
• The enableAnalytics method

It can be used as follows:

// Each method is destructurable from the composable and can be
// used on the server and client-side
const { gtag, initialize, disableAnalytics, enableAnalytics } = useGtag()

Type Declarations

function useGtag(): {
  gtag: Gtag
  initialize: (id?: string) => void
  disableAnalytics: (id?: string) => void
  enableAnalytics: (id?: string) => void
}

gtag

The gtag function is the main interface to the gtag.js instance and can be used to run every gtag.js command.

[!NOTE] Since the gtag.js instance is available in the client only, any gtag() calls executed on the server will have no effect.

Example

The following event command fires the event screen_view with two parameters: app_name and screen_name.

const { gtag } = useGtag()

// SSR-ready
gtag('event', 'screen_view', {
  app_name: 'My App',
  screen_name: 'Home'
})

Type Declarations

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

If you want to manually manage the initialization of the Google tag script, i.e. for GDPR compliance, you can use the initialize method to inject the gtag.js script to the document's head after the user has accepted your privacy policy. Make sure to set enabled to false in the Nuxt module for this to work.

The function accepts an optional ID in case you want to initialize a custom Google tag ID, which isn't set in the module options.

Example

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] Although this method is SSR-safe, the gtag.js script will be loaded in the client only. Make sure to run this method in the client.

Type Declarations

function initialize(id?: string): void

disableAnalytics

In some cases, it may be necessary to disable Google Analytics without removing the Google tag. For example, you might want to provide users with the option to opt out of tracking.

The gtag.js library includes a window property that, toggles gtag.js from sending data to Google Analytics. When Google Analytics attempts to set a cookie or send data back to the Google Analytics servers, this property is checked to determine whether to allow the action.

Example

const { disableAnalytics } = useGtag()

disableAnalytics()

Type Declarations

function disableAnalytics(id?: string): void

enableAnalytics

The enableAnalytics method is the counterpart to disableAnalytics and can be used to re-enable Google Analytics after it has been disabled.

Example

const { enableAnalytics } = useGtag()

enableAnalytics()

Type Declarations

function enableAnalytics(id?: string): void

useTrackEvent

Track your defined goals by passing the following parameters:

• The name of the recommended or custom event.
• A collection of parameters that provide additional information about the event (optional).

[!NOTE] This composable is SSR-ready. But since the gtag.js instance is available in the client only, executing the composable on the server will have no effect.

Example

For example, the following is an event called login with a parameter method:

// Tracks the `login` event
useTrackEvent('login', {
  method: 'Google'
})

Type Declarations

function useTrackEvent(
  eventName: EventNames | (string & {}),
  eventParams?: ControlParams | EventParams | CustomParams
): void

💻 Development

1. Clone this repository
2. Enable Corepack using corepack enable
3. Install dependencies using pnpm install
4. Run pnpm run dev:prepare
5. Start development server using pnpm run dev

Migration

v2.x to v3.x

In v2.x and earlier, the enabled option was used to control manual initialization of the Google tag script. This option has been replaced with initMode in v3.x. To migrate your configuration, set the initMode option to manual:

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

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

The enabled option is still available in v3.x, but is now used to disable the Google tag module for the current environment. This is useful if you want to disable the module in development or staging environments:

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

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

Credits

• Maronbeere for his logo pixel art.
• Junyoung Choi and Lucas Akira Uehara for their Google gtag.js API type definitions

License

MIT License © 2023-PRESENT Johann Schopplich