From 8b46f306c81919be4acad581f67ad61ddf1007a5 Mon Sep 17 00:00:00 2001
From: harlan <harlan@harlanzw.com>
Date: Sun, 15 Sep 2024 19:25:27 +1000
Subject: [PATCH] doc(googleTagManager): add guide for sending page events

---
 .../scripts/tracking/google-tag-manager.md    | 53 +++++++++++--------
 1 file changed, 32 insertions(+), 21 deletions(-)

diff --git a/docs/content/scripts/tracking/google-tag-manager.md b/docs/content/scripts/tracking/google-tag-manager.md
index 3c21cb0b..d447daeb 100644
--- a/docs/content/scripts/tracking/google-tag-manager.md
+++ b/docs/content/scripts/tracking/google-tag-manager.md
@@ -20,13 +20,9 @@ Nuxt Scripts provides many features you can easily
 implement within your Nuxt app. If you're using GTM for Google Tag Manager, you can use the `useScriptGoogleAnalytics` composable instead.
 ::
 
-### Nuxt Config Setup
+## Loading Globally
 
-The simplest way to load Google Tag Manager globally in your Nuxt App is to use Nuxt config. Alternatively you can directly
-use the [useScriptGoogleTagManager](#useScriptGoogleTagManager) composable.
-
-If you don't plan to send custom events you can use the [Environment overrides](https://nuxt.com/docs/getting-started/configuration#environment-overrides) to
-disable the script in development.
+If you'd like to avoid loading the analytics in development, you can use the [Environment overrides](https://nuxt.com/docs/getting-started/configuration#environment-overrides) in your Nuxt config.
 
 ::code-group
 
@@ -35,7 +31,7 @@ export default defineNuxtConfig({
   scripts: {
     registry: {
       googleTagManager: {
-        id: 'YOUR_ID'
+        id: '<YOUR_ID>'
       }
     }
   }
@@ -48,7 +44,7 @@ export default defineNuxtConfig({
     scripts: {
       registry: {
         googleTagManager: {
-          token: 'YOUR_TOKEN_ID',
+          id: '<YOUR_ID>',
         }
       }
     }
@@ -56,13 +52,7 @@ export default defineNuxtConfig({
 })
 ```
 
-::
-
-#### With Environment Variables
-
-If you prefer to configure your id using environment variables.
-
-```ts [nuxt.config.ts]
+```ts [Environment Variables]
 export default defineNuxtConfig({
   scripts: {
     registry: {
@@ -74,7 +64,9 @@ export default defineNuxtConfig({
     public: {
       scripts: {
         googleTagManager: {
-          id: '', // NUXT_PUBLIC_SCRIPTS_GOOGLE_TAG_MANAGER_ID
+          // .env
+          // NUXT_PUBLIC_SCRIPTS_GOOGLE_TAG_MANAGER_ID=<your-id>
+          id: '', 
         },
       },
     },
@@ -82,23 +74,42 @@ export default defineNuxtConfig({
 })
 ```
 
-```text [.env]
-NUXT_PUBLIC_SCRIPTS_GOOGLE_TAG_MANAGER_ID=<YOUR_ID>
-```
+::
 
 ## useScriptGoogleTagManager
 
 The `useScriptGoogleTagManager` composable lets you have fine-grain control over when and how Google Tag Manager is loaded on your site.
 
+
 ```ts
 const { proxy } = useScriptGoogleTagManager({
-  id: 'YOUR_ID'
+  id: 'YOUR_ID' // id is only needed if you haven't configured globally
 })
 // example
 proxy.dataLayer.push({ event: 'conversion', value: 1 })
 ```
 
-Please follow the [Registry Scripts](/docs/guides/registry-scripts) guide to learn more about advanced usage.
+Please follow the [Registry Scripts](/docs/guides/registry-scripts) guide to learn more about `proxy`.
+
+### Guide: Sending Page Events
+
+If you'd like to manually send page events to Google Tag Manager, you can use the `proxy` with the [useScriptEventPage](/docs/api/use-script-event-tag) composable.
+This composable will trigger the provided function on route change after the page title has been updated.
+
+```ts
+const { proxy } = useScriptGoogleTagManager({
+  id: 'YOUR_ID' // id is only needed if you haven't configured globally
+}) 
+
+useScriptEventPage((title, path) => {
+  // triggered on route change after title is updated
+  proxy.dataLayer.push({ 
+    event: 'pageview',
+    title, 
+    path 
+  })
+})
+```
 
 ### GoogleTagManagerApi