fix(googleAnalytics): support customer ids

Fixes #246

Author: harlan-zw

docs/content/scripts/analytics/google-analytics.md

@@ -142,16 +142,49 @@ You must provide the options when setting up the script for the first time.
 ```ts
 export const GoogleAnalyticsOptions = object({
   /**
-   * The Google Analytics ID.
+   * The Google Analytics ID. Optional - allows loading gtag.js without initial configuration.
    */
-  id: string(),
+  id: optional(string()),
   /**
    * The datalayer's name you want it to be associated with
    */
   l: optional(string())
 })
 ```
 
+### Customer/Consumer ID Tracking
+
+For e-commerce or multi-tenant applications where you need to track customer-specific analytics alongside your main tracking:
+
+```vue [ProductPage.vue]
+<script setup lang="ts">
+// Product page with customer-specific tracking
+const route = useRoute()
+const pageData = await $fetch(`/api/product/${route.params.id}`)
+
+// Load gtag with a custom dataLayer name for customer tracking
+const { proxy: customerGtag, load } = useScriptGoogleAnalytics({
+  key: 'gtag-customer',
+  l: 'customerDataLayer', // Custom dataLayer name
+})
+
+// Configure customer's tracking ID when available
+const consumerGtagId = computed(() => pageData?.gtag)
+
+if (consumerGtagId.value) {
+  // Configure the customer's GA4 property
+  customerGtag.gtag('config', consumerGtagId.value)
+
+  // Send customer-specific events
+  customerGtag.gtag('event', 'product_view', {
+    item_id: pageData.id,
+    customer_id: pageData.customerId,
+    value: pageData.price
+  })
+}
+</script>
+```
+
 ## Example
 
 Using Google Analytics only in production while using `gtag` to send a conversion event.

playground/pages/features/custom-registry.vue

@@ -7,8 +7,6 @@ const { proxy, status } = useScriptMyCustomScript({
   apiKey: 'demo-api-key-123',
   scriptOptions: {
     trigger: 'onNuxtReady',
-    // Add some DevTools metadata for demonstration
-    performanceMarkFeature: 'custom-registry-demo',
   },
 })
 

playground/pages/third-parties/google-analytics/optional-id.vue

@@ -0,0 +1,92 @@
+<script lang="ts" setup>
+import { useHead } from '#imports'
+
+useHead({
+  title: 'Google Analytics - Optional ID Loading',
+})
+
+// Simulate dynamic customer data
+const customerData = ref<{ gtagId?: string }>({})
+const isCustomerLoaded = ref(false)
+
+// Load gtag.js without initial ID
+const { proxy: gtagProxy, status } = useScriptGoogleAnalytics({
+  key: 'gtag-optional',
+})
+
+// Simulate loading customer data
+function loadCustomerData() {
+  customerData.value = { gtagId: 'G-CUSTOMER123' }
+  isCustomerLoaded.value = true
+
+  // Now configure gtag with the customer ID
+  gtagProxy.gtag('config', customerData.value.gtagId!)
+
+  // Send a test event
+  gtagProxy.gtag('event', 'customer_loaded', {
+    customer_id: 'test-customer',
+    value: 1,
+  })
+}
+
+// Load additional ID dynamically
+function loadAdditionalId() {
+  gtagProxy.gtag('config', 'G-ADDITIONAL456')
+  gtagProxy.gtag('event', 'additional_tracking', {
+    source: 'dynamic_load',
+  })
+}
+
+// Test sending events
+function sendTestEvent() {
+  gtagProxy.gtag('event', 'test_interaction', {
+    event_category: 'user_action',
+    event_label: 'button_click',
+  })
+}
+</script>
+
+<template>
+  <div class="space-y-4 p-4">
+    <h1 class="text-2xl font-bold">
+      Google Analytics - Optional ID Loading
+    </h1>
+
+    <div class="p-4 rounded">
+      <h2 class="font-semibold mb-2">
+        Status
+      </h2>
+      <ClientOnly>
+        <div>Script status: {{ status }}</div>
+        <div>Customer loaded: {{ isCustomerLoaded }}</div>
+        <div>Customer ID: {{ customerData.gtagId || 'Not loaded' }}</div>
+      </ClientOnly>
+    </div>
+
+    <div class="space-y-2">
+      <button
+        class="bg-blue-500 text-white px-4 py-2 rounded hover:bg-blue-600"
+        :disabled="isCustomerLoaded"
+        @click="loadCustomerData"
+      >
+        {{ isCustomerLoaded ? 'Customer Data Loaded' : 'Load Customer Data' }}
+      </button>
+
+      <button
+        class="bg-green-500 text-white px-4 py-2 rounded hover:bg-green-600"
+        :disabled="status !== 'awaitingLoad'"
+        @click="loadAdditionalId"
+      >
+        Load Additional ID
+      </button>
+
+      <button
+        class="bg-purple-500 text-white px-4 py-2 rounded hover:bg-purple-600"
+        :disabled="!isCustomerLoaded"
+        @click="sendTestEvent"
+      >
+        Send Test Event
+      </button>
+    </div>
+  </div>
+</template>

src/runtime/registry/google-analytics.ts

@@ -108,7 +108,7 @@ export interface GoogleAnalyticsApi {
 }
 
 export const GoogleAnalyticsOptions = object({
-  id: string(), // The GA4 measurement ID (format: G-XXXXXXXX)
+  id: optional(string()), // The GA4 measurement ID (format: G-XXXXXXXX)
   l: optional(string()), // Optional global name for dataLayer (defaults to 'dataLayer')
 })
 
@@ -143,7 +143,9 @@ export function useScriptGoogleAnalytics<T extends GoogleAnalyticsApi>(_options?
           // @ts-ignore
             _options?.onBeforeGtagStart?.(w.gtag)
             w.gtag('js', new Date())
-            w.gtag('config', (options?.id))
+            if (options?.id) {
+              w.gtag('config', (options?.id))
+            }
           },
     }
   }, _options)