Nuxt Google Tag

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

• ✨  Release Notes

Features

• 🌻 Loads no tracking library of its own, only 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 nuxt 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).

// `nuxt.config.ts`
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. Expand the “Enhanced measurement” switch button.
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')
}

Multi-Tenancy with Consent Mode

You can combine dynamic tag IDs with consent mode by setting initCommands in your config without a static id. This is useful when you need to set consent defaults before knowing which tenant's tag ID to load:

// nuxt.config.ts
export default defineNuxtConfig({
  modules: ['nuxt-gtag'],

  gtag: {
    initMode: 'manual',
    // No static ID needed for multi-tenant apps
    initCommands: [
      ['consent', 'default', {
        analytics_storage: 'denied',
        ad_storage: 'denied',
        ad_user_data: 'denied',
        ad_personalization: 'denied',
        wait_for_update: 500,
      }]
    ]
  }
})

Then initialize with tenant-specific IDs at runtime. The initCommands will be automatically applied:

const { gtag, initialize } = useGtag()

// Consent defaults are applied when initializing with dynamic ID
initialize('G-TENANT-123')

// Later, after user grants consent
gtag('consent', 'update', {
  analytics_storage: 'granted',
  ad_storage: 'granted',
  ad_user_data: 'granted',
  ad_personalization: 'granted'
})

Module Options

Composables

As with other composables in the Nuxt 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 initMode to manual in the module options for this to work.

The function accepts an optional ID for a Google tag that the module options do not carry. The ID joins the ones from your configuration rather than replacing them, so the call configures that tag and every tag still waiting.

A tag ID is configured once. Calling initialize again passes only the IDs it hasn't configured yet to the config command, so a consent flow may call it as often as it needs to.

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['ga-disable-GA_MEASUREMENT_ID'] property that, when set to true, disables 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.

The optional ID names the tag to switch off. It covers one tag, so a setup with multiple tag IDs needs one call per tag – without an argument, only the first configured tag is affected.

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. Its id parameter selects the tag the same way.

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

Credits

• Konkon 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