nuxt-gtag

Nuxt Gtag

Nuxt module to integrate Google Analytics 4.

Features

• 🌻 No dependencies except Google's gtag.js
• 🤝 Manual consent management for GDPR compliance
• 📯 Track events manually with composables
• 🏷️ Fully typed gtag.js API
• 🦾 SSR-ready
• 📂 .env file support

Setup

# pnpm
pnpm add -D nuxt-gtag

# npm
npm i -D nuxt-gtag

# yarn
yarn add -D nuxt-gtag

Basic Usage

Add nuxt-gtag to the modules section of your Nuxt configuration and provide your Google Analytics measurement ID.

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

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

Done! Google Analytics will now run in your application's client.

[!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, toggle the switch button near “Enhanced measurement”.

Configuration

All supported module options can be configured using the gtag key in your Nuxt configuration:

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

  gtag: {
    // The Google Analytics 4 property ID to use for tracking
    id: 'G-XXXXXXXXXX',
    // Additional configuration for the Google Analytics 4 property
    config: {
      page_title: 'My Custom Page Title'
    }
  }
})

Runtime Config

Instead of hard-coding your measurement 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 measurement ID.

Consent Management

If you want to disable tracking by default, you can set the initialConsent option to false. This will prevent the gtag.js script from loading until the user has consented to tracking.

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

  gtag: {
    id: 'G-XXXXXXXXXX',
    initialConsent: false
  }
})

To manually manage consent, you can use the grantConsent method destructurable from useGtag to set the consent state, e.g. after the user has accepted your cookie policy.

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

<template>
  <button @click="grantConsent()">
    Accept Tracking
  </button>
</template>

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

const { gtag, grantConsent, revokeConsent } = useGtag()

function acceptTracking() {
  grantConsent('G-XXXXXXXXXX')
}

Module Options

Option	Type	Default	Description
id	string	undefined	The Google Analytics measurement ID.
config	Record<string, any>	{}	The configuration parameters to be passed to gtag.js on initialization.
initialConsent	boolean	true	Whether to initially consent to tracking.
loadingStrategy	'async' | 'defer'	'defer'	The loading strategy to be used for the gtag.js script.

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 grantConsent method
• The revokeConsent method

It can be used as follows:

// SSR-ready
const { gtag } = useGtag()
gtag('<command>', '<command-parameters>')

Type Declarations

function useGtag(): {
  gtag: Gtag
  grantConsent: (id?: string) => void
  revokeConsent: (id?: string) => void
}

gtag

The gtag function is the main interface to the gtag.js instance and can be used to call any of the gtag.js methods.

const { gtag } = useGtag()

// SSR-ready
gtag('<command>', '<command-parameters>')

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

Type Declarations

const gtag: {
  (command: 'config', targetId: string, config?: ControlParams | EventParams | ConfigParams | Record<string, any>): void
  (command: 'set', targetId: string, config: string | boolean | Record<string, any>): void
  (command: 'set', config: Record<string, any>): void
  (command: 'js', config: Date): void
  (command: 'event', eventName: EventNames | (string & Record<never, never>), eventParams?: ControlParams | EventParams | Record<string, any>): void
  (command: 'get', targetId: string, fieldName: FieldNames | string, callback?: (field?: string | Record<string, any>) => any): void
  (command: 'consent', consentArg: ConsentArg | string, consentParams: ConsentParams): void
}

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

grantConsent

If you want to manually manage consent, i.e. for GDPR compliance, you can use the grantConsent method to grant the consent. Make sure to set initialConsent to false in the module options beforehand.

This function accepts an optional ID in case you want to initialize a custom Gtag ID and haven't set it in the module options.

const { grantConsent } = useGtag()

// When called, the `gtag.js` script will be loaded and tracking will begin
grantConsent()

[!NOTE] 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 grantConsent(id?: string): void

revokeConsent

If a user has previously granted consent, you can use the revokeConsent method to revoke the consent. This will prevent the gtag.js script from tracking any events until the consent is granted again.

This function accepts an optional ID in case you haven't set it in the module options. Make sure to pass the same ID that was used to grant the consent.

const { revokeConsent } = useGtag()

// When called, the `gtag.js` script will be stopped from tracking events
revokeConsent()

Type Declarations

function revokeConsent(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.

Type Declarations

function useTrackEvent(
  eventName: string,
  eventParams?: Record<string, any>
): void

Example

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

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

💻 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

• 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