fix(GoogleTagManager): add all query params

Fixes #434

Author: harlan-zw

docs/content/scripts/tracking/google-tag-manager.md

@@ -121,23 +121,46 @@ interface GoogleTagManagerApi {
 You must provide the options when setting up the script for the first time.
 
 ```ts
+/**
+ * GTM configuration options with improved documentation
+ */
 export const GoogleTagManagerOptions = object({
-  /**
-   * The Google Tag Manager ID.
-   */
-  id: string(),
-  /**
-   * The name of the dataLayer you want to use
-   * @default 'dataLayer'
-   */
-  dataLayerName: optional(string())
-})
+    /** GTM container ID (format: GTM-XXXXXX) */
+    id: string(),
+
+    /** Optional dataLayer variable name */
+    l: optional(string()),
+
+    /** Authentication token for environment-specific container versions */
+    auth: optional(string()),
+
+    /** Preview environment name */
+    preview: optional(string()),
+
+    /** Forces GTM cookies to take precedence when true */
+    cookiesWin: optional(union([boolean(), literal('x')])),
+
+    /** Enables debug mode when true */
+    debug: optional(union([boolean(), literal('x')])),
+
+    /** No Personal Advertising - disables advertising features when true */
+    npa: optional(union([boolean(), literal('1')])),
+
+    /** Custom dataLayer name (alternative to "l" property) */
+    dataLayer: optional(string()),
+
+    /** Environment name for environment-specific container */
+    envName: optional(string()),
+
+    /** Referrer policy for analytics requests */
+    authReferrerPolicy: optional(string()),
+  })
 ```
 
 ### Options types
 
 ```ts
-type GoogleTagManagerInput = typeof GoogleTagManagerOptions & { onBeforeGtmStart?: ((gtag: Gtag) => void) => void }
+type GoogleTagManagerInput = typeof GoogleTagManagerOptions & { onBeforeGtmStart?: (gtag: Gtag) => void }
 ```
 
 ## Example

playground/pages/features/cookie-consent.vue

@@ -9,7 +9,7 @@ function acceptCookies() {
   showCookieBanner.value = false
 }
 useScriptGoogleTagManager({
-  id: 'GTM-5ZQZJZ',
+  id: 'GTM-MWW974PF',
   scriptOptions: {
     trigger: scriptConsent,
     bundle: true,

playground/pages/features/on-nuxt-ready.vue

@@ -2,7 +2,7 @@
 import { useScriptGoogleTagManager } from '#imports'
 
 const { status } = useScriptGoogleTagManager({
-  id: 'GTM-5ZQZJZ',
+  id: 'GTM-MWW974PF',
   scriptOptions: {
     trigger: 'onNuxtReady', // this is the default behavior
     bundle: true,

playground/pages/third-parties/google-tag-manager.vue

@@ -1,22 +1,14 @@
 <script lang="ts" setup>
-import { useHead, useScriptGoogleTagManager } from '#imports'
+import { useScriptGoogleTagManager } from '#nuxt-scripts/registry/google-tag-manager'
+import { useHead } from '#imports'
 
 useHead({
   title: 'Google Analytics',
 })
 
 // composables return the underlying api as a proxy object and the script state
 const { proxy, onLoaded, status } = useScriptGoogleTagManager({
-  id: 'GTM-MNJD4B',
-  onBeforeGtmStart(gtag) {
-    gtag('consent', 'default', {
-      ad_user_data: 'denied',
-      ad_personalization: 'denied',
-      ad_storage: 'denied',
-      analytics_storage: 'denied',
-      wait_for_update: 500,
-    })
-  },
+  id: 'GTM-MWW974PF',
 }) // id is set via runtime config
 proxy.dataLayer.push({
   event: 'page_view',

src/registry.ts

@@ -248,7 +248,18 @@ export async function registry(resolve?: (path: string, opts?: ResolvePathOption
       },
       logo: `<svg xmlns="http://www.w3.org/2000/svg" width="32" height="32" viewBox="0 0 256 256"><path fill="#8AB4F8" d="m150.262 245.516l-44.437-43.331l95.433-97.454l46.007 45.091z"/><path fill="#4285F4" d="M150.45 53.938L106.176 8.731L9.36 104.629c-12.48 12.48-12.48 32.713 0 45.207l95.36 95.986l45.09-42.182l-72.654-76.407z"/><path fill="#8AB4F8" d="m246.625 105.37l-96-96c-12.494-12.494-32.756-12.494-45.25 0c-12.495 12.495-12.495 32.757 0 45.252l96 96c12.494 12.494 32.756 12.494 45.25 0c12.495-12.495 12.495-32.757 0-45.251"/><circle cx="127.265" cy="224.731" r="31.273" fill="#246FDB"/></svg>`,
       scriptBundling(options) {
-        return withQuery('https://www.googletagmanager.com/gtag/js', { id: options?.id, l: options?.l })
+        return withQuery('https://www.googletagmanager.com/gtm.js', {
+          id: options.id,
+          l: options.l,
+          gtm_auth: options.auth,
+          gtm_preview: options.preview,
+          gtm_cookies_win: options.cookiesWin ? 'x' : undefined,
+          gtm_debug: options.debug ? 'x' : undefined,
+          gtm_npa: options.npa ? '1' : undefined,
+          gtm_data_layer: options.dataLayer,
+          gtm_env: options.envName,
+          gtm_auth_referrer_policy: options.authReferrerPolicy,
+        })
       },
     },
     {

src/runtime/registry/google-tag-manager.ts

@@ -1,70 +1,183 @@
 import { withQuery } from 'ufo'
 import type { GTag } from './google-analytics'
 import { useRegistryScript } from '#nuxt-scripts/utils'
-import type { RegistryScriptInput } from '#nuxt-scripts/types'
-import { object, string, optional } from '#nuxt-scripts-validator'
-
-type DataLayer = Array<Parameters<GTag> | Record<string, unknown>>
-interface GoogleTagManagerDataLayerApi {
-  name: 'dataLayer'
-  set: (opt: {
-    [key: string]: string
-  }) => void
-  get: (key: string) => void
+import type { NuxtUseScriptOptions, RegistryScriptInput, UseFunctionType, UseScriptContext } from '#nuxt-scripts/types'
+import { object, string, optional, boolean, union, literal } from '#nuxt-scripts-validator'
+
+/**
+ * Improved DataLayer type that better reflects GTM's capabilities
+ * Can contain either gtag event parameters or custom data objects
+ */
+export type DataLayerItem = Parameters<GTag> | Record<string, unknown>
+export type DataLayer = Array<DataLayerItem>
+
+/**
+ * DataLayer push function type
+ */
+export interface DataLayerPush {
+  (...args: Parameters<GTag>): void
+  (obj: Record<string, unknown>): void
+}
+
+/**
+ * Improved DataLayer API type with more precise methods
+ */
+export interface GoogleTagManagerDataLayerApi {
+  name: string
+  push: DataLayerPush
+  set: (config: Record<string, unknown>) => void
+  get: <T = unknown>(key: string) => T
   reset: () => void
+  listeners: Array<() => void>
 }
-interface GoogleTagManagerDataLayerStatus {
+
+/**
+ * DataLayer status information
+ */
+export interface GoogleTagManagerDataLayerStatus {
   dataLayer: {
     gtmDom: boolean
     gtmLoad: boolean
     subscribers: number
+    [key: string]: unknown
   }
 }
-type GoogleTagManagerInstance = GoogleTagManagerDataLayerStatus & {
-  [key: string]: {
-    callback: () => void
-    dataLayer: GoogleTagManagerDataLayerApi
-  }
+
+/**
+ * Container instance type
+ */
+export interface GoogleTagManagerContainer {
+  callback: () => void
+  dataLayer: GoogleTagManagerDataLayerApi
+  state: Record<string, unknown>
 }
-interface GoogleTagManagerApi {
+
+/**
+ * Complete GTM instance object
+ */
+export interface GoogleTagManagerInstance extends GoogleTagManagerDataLayerStatus {
+  [containerId: string]: GoogleTagManagerContainer | any
+}
+
+/**
+ * Complete Google Tag Manager API accessible via window
+ */
+export interface GoogleTagManagerApi {
   google_tag_manager: GoogleTagManagerInstance
-  dataLayer: DataLayer
+  dataLayer: DataLayer & {
+    push: DataLayerPush
+  }
 }
 
+/**
+ * Enhanced window type with GTM
+ */
 declare global {
   interface Window extends GoogleTagManagerApi {}
 }
+
+/**
+ * GTM configuration options with improved documentation
+ */
 export const GoogleTagManagerOptions = object({
+  /** GTM container ID (format: GTM-XXXXXX) */
   id: string(),
+
+  /** Optional dataLayer variable name */
   l: optional(string()),
+
+  /** Authentication token for environment-specific container versions */
+  auth: optional(string()),
+
+  /** Preview environment name */
+  preview: optional(string()),
+
+  /** Forces GTM cookies to take precedence when true */
+  cookiesWin: optional(union([boolean(), literal('x')])),
+
+  /** Enables debug mode when true */
+  debug: optional(union([boolean(), literal('x')])),
+
+  /** No Personal Advertising - disables advertising features when true */
+  npa: optional(union([boolean(), literal('1')])),
+
+  /** Custom dataLayer name (alternative to "l" property) */
+  dataLayer: optional(string()),
+
+  /** Environment name for environment-specific container */
+  envName: optional(string()),
+
+  /** Referrer policy for analytics requests */
+  authReferrerPolicy: optional(string()),
 })
 
 export type GoogleTagManagerInput = RegistryScriptInput<typeof GoogleTagManagerOptions>
 
-export function useScriptGoogleTagManager<T extends GoogleTagManagerApi>(_options?: GoogleTagManagerInput & { onBeforeGtmStart?: (gtag: GTag) => void }) {
-  return useRegistryScript<T, typeof GoogleTagManagerOptions>(_options?.key || 'googleTagManager', options => ({
-    scriptInput: {
-      src: withQuery('https://www.googletagmanager.com/gtm.js', { id: options?.id, l: options?.l }),
-    },
-    schema: import.meta.dev ? GoogleTagManagerOptions : undefined,
-    scriptOptions: {
-      use: () => {
-        return { dataLayer: (window as any)[options.l ?? 'dataLayer'] as DataLayer, google_tag_manager: window.google_tag_manager }
-      },
-      performanceMarkFeature: 'nuxt-third-parties-gtm',
-      tagPriority: 1,
-    },
-    clientInit: import.meta.server
-      ? undefined
-      : () => {
-          const dataLayerName = options?.l ?? 'dataLayer';
-          (window as any)[dataLayerName] = (window as any)[(options?.l ?? 'dataLayer')] || []
-          function gtag() {
-            // eslint-disable-next-line prefer-rest-params
-            (window as any)[dataLayerName].push(arguments)
-          }
-          _options?.onBeforeGtmStart?.(gtag)
-          ;(window as any)[dataLayerName].push({ 'gtm.start': new Date().getTime(), 'event': 'gtm.js' })
+/**
+ * Hook to use Google Tag Manager in Nuxt applications
+ */
+export function useScriptGoogleTagManager<T extends GoogleTagManagerApi>(
+  options?: GoogleTagManagerInput & {
+    /**
+     * Optional callback that runs before GTM starts
+     * Allows for custom initialization or configuration
+     */
+    onBeforeGtmStart?: (gtag: DataLayerPush) => void
+  },
+): UseScriptContext<UseFunctionType<NuxtUseScriptOptions<T>, T>> {
+  return useRegistryScript<T, typeof GoogleTagManagerOptions>(
+    options?.key || 'googleTagManager',
+    (opts) => {
+      const dataLayerName = opts?.l ?? opts?.dataLayer ?? 'dataLayer'
+
+      return {
+        scriptInput: {
+          src: withQuery('https://www.googletagmanager.com/gtm.js', {
+            id: opts.id,
+            l: opts.l,
+            gtm_auth: opts.auth,
+            gtm_preview: opts.preview,
+            gtm_cookies_win: opts.cookiesWin ? 'x' : undefined,
+            gtm_debug: opts.debug ? 'x' : undefined,
+            gtm_npa: opts.npa ? '1' : undefined,
+            gtm_data_layer: opts.dataLayer,
+            gtm_env: opts.envName,
+            gtm_auth_referrer_policy: opts.authReferrerPolicy,
+          }),
         },
-  }), _options)
+        schema: import.meta.dev ? GoogleTagManagerOptions : undefined,
+        scriptOptions: {
+          use: () => {
+            return {
+              dataLayer: (window as any)[dataLayerName] as DataLayer & { push: DataLayerPush },
+              google_tag_manager: window.google_tag_manager,
+            }
+          },
+          performanceMarkFeature: 'nuxt-third-parties-gtm',
+          tagPriority: 1,
+        },
+        clientInit: import.meta.server
+          ? undefined
+          : () => {
+            // Initialize dataLayer if it doesn't exist
+              (window as any)[dataLayerName] = (window as any)[dataLayerName] || []
+
+              // Create gtag function
+              function gtag(...args: any[]) {
+                (window as any)[dataLayerName].push(args)
+              }
+
+              // Allow custom initialization
+              options?.onBeforeGtmStart?.(gtag);
+
+              // Push the standard GTM initialization event
+              (window as any)[dataLayerName].push({
+                'gtm.start': new Date().getTime(),
+                'event': 'gtm.js',
+              })
+            },
+      }
+    },
+    options,
+  )
 }