feat: initCommands

johannschopplich · Feb 27, 2024 · d97062e · d97062e
1 parent 903b933
commit d97062e
Show file tree

Hide file tree

Showing 6 changed files with 643 additions and 559 deletions.
diff --git a/README.md b/README.md
@@ -10,7 +10,7 @@
 
 - 🌻 Zero dependencies except Google's `gtag.js`
 - 🛍️ For Google Analytics 4, Google Ads and other products
-- 🛎️ Supports Google tag consent mode v2
+- 🛎️ Supports Google tag [consent mode v2](#set-up-consent-mode)
 - 🤝 Manual [consent management](#consent-management) for GDPR compliance
 - 🔢 Supports [multiple tag IDs](#multiple-google-tags)
 - 📯 Track events manually with [composables](#composables)
@@ -57,27 +57,30 @@ Done! The `gtag.js` script will be loaded and initialized client-side with your
 > 3. Click on your web data stream.
 > 4. Next, toggle the switch button near “Enhanced measurement”.
 
-### 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.
+## Configuration
 
-The following example shows how to load a second Google tag that is connected to a Floodlight destination. To send data to Floodlight (tag ID `DC-ZZZZZZZZZZ`), add another config command after initializing the first Google tag (tag ID `GT-XXXXXXXXXX`):
+All [supported module options](#module-options) can be configured using the `gtag` key in your Nuxt configuration. An example of some of the options you can set:
 
 ```ts
-// `nuxt.config.ts`
 export default defineNuxtConfig({
   modules: ['nuxt-gtag'],
 
   gtag: {
-    tags: [
-      'GT-XXXXXXXXXX', // Google Ads and GA4
-      'DC-ZZZZZZZZZZ' // Floodlight
-    ]
+    // Your primary Google tag ID
+    id: 'G-XXXXXXXXXX',
+    // Additional configuration for this tag ID
+    config: {
+      page_title: 'My Custom Page Title'
+    },
   }
 })
 ```
 
-Or use the object syntax to initialize multiple tags with different configurations:
+### 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:
 
 ```ts
 // `nuxt.config.ts`
@@ -86,60 +89,86 @@ export default defineNuxtConfig({
 
   gtag: {
     tags: [
+      // Google Ads and GA4, with additional configuration
       {
-        id: 'GT-XXXXXXXXXX',
+        id: 'G-XXXXXXXXXX',
         config: {
-          page_title: 'GA4'
+          page_title: 'My Custom Page Title'
         }
       },
-      {
-        id: 'DC-ZZZZZZZZZZ',
-        config: {
-          page_title: 'Floodlight'
-        }
-      }
+      // Second Google tag ID for Floodlight
+      'DC-ZZZZZZZZZZ'
     ]
   }
 })
 ```
 
-## Configuration
+### Runtime Config
 
-All [supported module options](#module-options) can be configured using the `gtag` key in your Nuxt configuration. An example of some of the options you can set:
+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](https://nuxt.com/docs/api/nuxt-config#runtimeconfig) by matching environment variables at runtime.
+
+```ini
+# 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.
+
+### Set Up Consent Mode
+
+> [!TIP]
+> Follows the [Google consent mode v2](https://developers.google.com/tag-platform/security/guides/consent) 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:
 
 ```ts
+// `nuxt.config.ts`
 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'
-    },
-
-    // To send data to multiple destinations, use this option instead:
-    tags: [
-      'GT-XXXXXXXXXX', // Google Ads and GA4
-      'DC-ZZZZZZZZZZ' // Floodlight
+    initCommands: [
+      // Setup up consent mode
+      ['consent', 'default', {
+        ad_user_data: 'denied',
+        ad_personalization: 'denied',
+        ad_storage: 'denied',
+        analytics_storage: 'denied',
+        wait_for_update: 500,
+      }]
     ]
   }
 })
 ```
 
-### Runtime Config
+After a user indicates their consent choices, update relevant parameters to `granted`:
 
-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](https://nuxt.com/docs/api/nuxt-config#runtimeconfig) by matching environment variables at runtime.
+```ts
+function allConsentGranted() {
+  const { gtag } = useGtag()
+  gtag('consent', 'update', {
+    ad_user_data: 'granted',
+    ad_personalization: 'granted',
+    ad_storage: 'granted',
+    analytics_storage: 'granted'
+  })
+}
 
-```ini
-# Overwrites the `gtag.id` module option
-NUXT_PUBLIC_GTAG_ID=G-XXXXXXXXXX
-```
+function consentGrantedAdStorage() {
+  const { gtag } = useGtag()
+  gtag('consent', 'update', {
+    ad_storage: 'granted'
+  })
+}
 
-With this setup, you can omit the `gtag` key in your Nuxt configuration if you only intend to set the Google tag ID.
+// Invoke the consent function when a user interacts with your banner
+consentGrantedAdStorage() // Or `allConsentGranted()`
+```
 
-### Consent Management
+### Delay Google Tag Script Loading
 
 For GDPR compliance, you may want to delay the loading of the `gtag.js` script until the user has granted consent. Set the `initialConsent` option to `false` to prevent the `gtag.js` script from loading until you manually enable it.
 
@@ -185,9 +214,9 @@ function acceptTracking() {
 | Option | Type | Default | Description |
 | --- | --- | --- | --- |
 | `id` | `string` | `undefined` | The Google tag ID to initialize. |
-| `config` | `GoogleTagOptions['config']` | `undefined` | The [configuration parameters](https://developers.google.com/analytics/devguides/collection/ga4/reference/config) to be passed to `gtag.js` on initialization. |
-| `config` | `GoogleTagOptions['commands']` | `undefined` | The [configuration parameters](https://developers.google.com/analytics/devguides/collection/ga4/reference/config) to be passed to `gtag.js` on initialization. |
-| `tags` | `string[] \| GoogleTagOptions[]` | `undefined` | Multiple Google tag IDs to initialize for sending data to different destinations. |
+| `initCommands` | `GoogleTagOptions['initCommands']` | `[]` | Commands to be executed when the Google tag ID is initialized. |
+| `config` | `GoogleTagOptions['config']` | `{}` | The [configuration parameters](https://developers.google.com/analytics/devguides/collection/ga4/reference/config) to be passed to `gtag.js` on initialization. |
+| `tags` | `string[] \| GoogleTagOptions[]` | `[]` | Multiple Google tag IDs to initialize for sending data to different destinations. |
 | `initialConsent` | `boolean` | `true` | Whether to initialize the Google tag script immediately after the page has loaded. |
 | `loadingStrategy` | `'async' \| 'defer'` | `'defer'` | The loading strategy to be used for the `gtag.js` script. |
 | `url` | `string` | `'https://www.googletagmanager.com/gtag/js'` | The URL to the `gtag.js` script. Use this option to load the script from a custom URL. |

diff --git a/package.json b/package.json
@@ -2,7 +2,7 @@
   "name": "nuxt-gtag",
   "type": "module",
   "version": "1.2.1",
-  "packageManager": "pnpm@8.15.3",
+  "packageManager": "pnpm@8.15.4",
   "description": "Natively integrates Google Tag into Nuxt",
   "author": "Johann Schopplich <pkg@johannschopplich.com>",
   "license": "MIT",
@@ -42,19 +42,19 @@
     "release": "bumpp --commit --push --tag"
   },
   "dependencies": {
-    "@nuxt/kit": "^3.10.2",
+    "@nuxt/kit": "^3.10.3",
     "defu": "^6.1.4",
     "pathe": "^1.1.2",
     "ufo": "^1.4.0"
   },
   "devDependencies": {
     "@antfu/eslint-config": "^2.6.4",
     "@nuxt/module-builder": "^0.5.5",
-    "@nuxt/schema": "^3.10.2",
-    "@types/node": "^20.11.19",
+    "@nuxt/schema": "^3.10.3",
+    "@types/node": "^20.11.20",
     "bumpp": "^9.3.0",
-    "eslint": "^8.56.0",
-    "nuxt": "^3.10.2",
+    "eslint": "^8.57.0",
+    "nuxt": "^3.10.3",
     "nuxt-gtag": "workspace:*",
     "typescript": "^5.3.3",
     "vue-tsc": "^1.8.27"