Skip to content

Commit 0613925

Browse files
harlan-zwharlan-zw
committedMar 25, 2025·
fix(GoogleAnalytics): improved type safety
Fixes #325 Fixes #410
·
v0.11.5v0.11.3
1 parent 6f54ffe commit 0613925

File tree

4 files changed

+182
-75
lines changed

4 files changed

+182
-75
lines changed
 

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

+20-18
Original file line numberDiff line numberDiff line change
@@ -109,24 +109,26 @@ The proxy exposes the `gtag` and `dataLayer` properties, and you should use them
109109
### GoogleAnalyticsApi
110110

111111
```ts
112-
interface GTag {
113-
(fn: 'js', opt: Date): void
114-
(fn: 'config', opt: string): void
115-
(fn: 'event', opt: string, opt2?: {
116-
[key: string]: any
117-
}): void
118-
(fn: 'set', opt: {
119-
[key: string]: string
120-
}): void
121-
(fn: 'get', opt: string): void
122-
(fn: 'consent', opt: 'default', opt2: {
123-
[key: string]: string
124-
}): void
125-
(fn: 'consent', opt: 'update', opt2: {
126-
[key: string]: string
127-
}): void
128-
(fn: 'config', opt: 'reset'): void
112+
export interface GTag {
113+
// Initialize gtag.js with timestamp
114+
(command: 'js', value: Date): void
115+
116+
// Configure a GA4 property
117+
(command: 'config', targetId: string, configParams?: ConfigParams): void
118+
119+
// Get a value from gtag
120+
(command: 'get', targetId: string, fieldName: string, callback?: (field: any) => void): void
121+
122+
// Send an event to GA4
123+
(command: 'event', eventName: DefaultEventName, eventParams?: EventParameters): void
124+
125+
// Set default parameters for all subsequent events
126+
(command: 'set', params: GtagCustomParams): void
127+
128+
// Update consent state
129+
(command: 'consent', consentArg: 'default' | 'update', consentParams: ConsentOptions): void
129130
}
131+
130132
interface GoogleAnalyticsApi {
131133
dataLayer: Record<string, any>[]
132134
gtag: GTag
@@ -146,7 +148,7 @@ export const GoogleAnalyticsOptions = object({
146148
/**
147149
* The datalayer's name you want it to be associated with
148150
*/
149-
dataLayerName: optional(string())
151+
l: optional(string())
150152
})
151153
```
152154

‎docs/snippets/_magic-api.md

+10-8
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,16 @@
1-
```vue
2-
<script lang="ts" setup>
1+
```ts
32
const { onLoaded, proxy } = useScriptGoogleAnalytics(
4-
{ id: 'G-1234567' },
5-
{ trigger: 'manual' }
3+
{
4+
id: 'G-1234567',
5+
scriptOptions: {
6+
trigger: 'manual',
7+
},
8+
},
69
)
7-
// send events
10+
// queue events to be sent when ga loads
811
proxy.gtag('config', 'UA-123456789-1')
9-
// ..
10-
onLoaded(() => {
12+
// or wait until ga is loaded
13+
onLoaded((gtag) => {
1114
// script loaded
1215
})
13-
</script>
1416
```

‎playground/pages/third-parties/google-analytics/nuxt-scripts.vue

+14-4
Original file line numberDiff line numberDiff line change
@@ -1,22 +1,32 @@
11
<script lang="ts" setup>
2-
import { useHead, useScriptGoogleAnalytics } from '#imports'
2+
import { useHead } from '#imports'
3+
import { useScriptGoogleAnalytics } from '#nuxt-scripts/registry/google-analytics'
34
45
useHead({
56
title: 'Google Analytics',
67
})
78
89
// composables return the underlying api as a proxy object and the script state
9-
const { gtag, status } = useScriptGoogleAnalytics({
10+
const { proxy, status } = useScriptGoogleAnalytics({
1011
id: 'G-TR58L0EF8P',
12+
onBeforeGtagStart(gtag) {
13+
gtag('consent', 'default', {
14+
ad_user_data: 'denied',
15+
ad_personalization: 'denied',
16+
ad_storage: 'denied',
17+
analytics_storage: 'denied',
18+
wait_for_update: 500,
19+
})
20+
},
1121
}) // id set via nuxt scripts module config
12-
gtag('event', 'page_view', {
22+
proxy.gtag('event', 'page_view', {
1323
page_title: 'Google Analytics',
1424
page_location: 'https://harlanzw.com/third-parties/google-analytics',
1525
page_path: '/third-parties/google-analytics',
1626
})
1727
1828
function triggerConversion() {
19-
gtag('event', 'conversion')
29+
proxy.gtag('event', 'conversion')
2030
}
2131
</script>
2232

‎src/runtime/registry/google-analytics.ts

+138-45
Original file line numberDiff line numberDiff line change
@@ -3,63 +3,156 @@ import { useRegistryScript } from '#nuxt-scripts/utils'
33
import type { RegistryScriptInput } from '#nuxt-scripts/types'
44
import { object, string, optional } from '#nuxt-scripts-validator'
55

6-
type ConsentOptions = 'default' | 'update'
6+
export type GtagCustomParams = Record<string, any>
77

8+
// Consent mode types
9+
export type ConsentStatus = 'granted' | 'denied'
10+
11+
export interface ConsentOptions {
12+
ad_user_data?: ConsentStatus
13+
ad_personalization?: ConsentStatus
14+
ad_storage?: ConsentStatus
15+
analytics_storage?: ConsentStatus
16+
functionality_storage?: ConsentStatus
17+
personalization_storage?: ConsentStatus
18+
security_storage?: ConsentStatus
19+
wait_for_update?: number
20+
region?: string[]
21+
}
22+
23+
// Config parameters type
24+
export interface ConfigParams extends GtagCustomParams {
25+
send_page_view?: boolean
26+
transport_url?: string
27+
cookie_domain?: string
28+
cookie_prefix?: string
29+
cookie_expires?: number
30+
cookie_update?: boolean
31+
cookie_flags?: string
32+
user_id?: string
33+
}
34+
35+
// Event parameters with common GA4 event parameters
36+
export interface EventParameters extends GtagCustomParams {
37+
value?: number
38+
currency?: string
39+
transaction_id?: string
40+
items?: Array<{
41+
item_id?: string
42+
item_name?: string
43+
item_category?: string
44+
item_variant?: string
45+
price?: number
46+
quantity?: number
47+
[key: string]: any
48+
}>
49+
[key: string]: any
50+
}
51+
52+
// Default events in GA4
53+
export type DefaultEventName =
54+
| 'add_payment_info'
55+
| 'add_shipping_info'
56+
| 'add_to_cart'
57+
| 'add_to_wishlist'
58+
| 'begin_checkout'
59+
| 'purchase'
60+
| 'refund'
61+
| 'remove_from_cart'
62+
| 'select_item'
63+
| 'select_promotion'
64+
| 'view_cart'
65+
| 'view_item'
66+
| 'view_item_list'
67+
| 'view_promotion'
68+
| 'login'
69+
| 'sign_up'
70+
| 'search'
71+
| 'page_view'
72+
| 'screen_view'
73+
| string // Allow custom event names
74+
75+
// Define the GTag function interface with proper overloads
876
export interface GTag {
9-
(fn: 'js', opt: Date): void
10-
(fn: 'config' | 'get', opt: string): void
11-
(fn: 'event', opt: string, opt2?: Record<string, any>): void
12-
(fn: 'set', opt: Record<string, string>): void
13-
(fn: 'consent', opt: ConsentOptions, opt2: Record<string, string | number>): void
77+
// Initialize gtag.js with timestamp
78+
(command: 'js', value: Date): void
79+
80+
// Configure a GA4 property
81+
(command: 'config', targetId: string, configParams?: ConfigParams): void
82+
83+
// Get a value from gtag
84+
(command: 'get', targetId: string, fieldName: string, callback?: (field: any) => void): void
85+
86+
// Send an event to GA4
87+
(command: 'event', eventName: DefaultEventName, eventParams?: EventParameters): void
88+
89+
// Set default parameters for all subsequent events
90+
(command: 'set', params: GtagCustomParams): void
91+
92+
// Update consent state
93+
(command: 'consent', consentArg: 'default' | 'update', consentParams: ConsentOptions): void
1494
}
15-
type DataLayer = Array<Parameters<GTag> | Record<string, unknown>>
1695

17-
export const GoogleAnalyticsOptions = object({
18-
id: string(),
19-
l: optional(string()),
20-
})
96+
// Define the dataLayer array type
97+
export interface DataLayerObject {
98+
event?: string
99+
[key: string]: any
100+
}
21101

22-
export type GoogleAnalyticsInput = RegistryScriptInput<typeof GoogleAnalyticsOptions>
102+
export type DataLayer = Array<DataLayerObject>
23103

104+
// Define the complete Google Analytics API interface
24105
export interface GoogleAnalyticsApi {
25106
gtag: GTag
26107
dataLayer: DataLayer
27108
}
28109

29-
export function useScriptGoogleAnalytics<T extends GoogleAnalyticsApi>(_options?: GoogleAnalyticsInput) {
30-
return useRegistryScript<T, typeof GoogleAnalyticsOptions>(_options?.key || 'googleAnalytics', options => ({
31-
scriptInput: {
32-
src: withQuery('https://www.googletagmanager.com/gtag/js', { id: options?.id, l: options?.l }),
33-
},
34-
schema: import.meta.dev ? GoogleAnalyticsOptions : undefined,
35-
scriptOptions: {
36-
use: () => {
37-
const gtag: GTag = function (...args: Parameters<GTag>) {
38-
((window as any)['gtag-' + (options.l ?? 'dataLayer')] as GTag)(...args)
39-
} as GTag
40-
return {
41-
dataLayer: (window as any)[options.l ?? 'dataLayer'] as DataLayer,
42-
gtag,
43-
}
110+
export const GoogleAnalyticsOptions = object({
111+
id: string(), // The GA4 measurement ID (format: G-XXXXXXXX)
112+
l: optional(string()), // Optional global name for dataLayer (defaults to 'dataLayer')
113+
})
114+
115+
export type GoogleAnalyticsInput = RegistryScriptInput<typeof GoogleAnalyticsOptions>
116+
117+
export function useScriptGoogleAnalytics<T extends GoogleAnalyticsApi>(_options?: GoogleAnalyticsInput & { onBeforeGtagStart?: (gtag: GTag) => void }) {
118+
return useRegistryScript<T, typeof GoogleAnalyticsOptions>(_options?.key || 'googleAnalytics', (options) => {
119+
const dataLayerName = options?.l ?? 'dataLayer'
120+
const w = import.meta.client ? window as any : {}
121+
return {
122+
scriptInput: {
123+
src: withQuery('https://www.googletagmanager.com/gtag/js', { id: options?.id, l: options?.l }),
44124
},
45-
performanceMarkFeature: 'nuxt-third-parties-ga',
46-
tagPriority: 1,
47-
},
48-
clientInit: import.meta.server
49-
? undefined
50-
: () => {
51-
const dataLayerName = options?.l ?? 'dataLayer'
52-
const dataLayer = (window as any)[dataLayerName] || [];
53-
54-
(window as any)[dataLayerName] = dataLayer
55-
// eslint-disable-next-line
56-
// @ts-ignore
57-
window['gtag-' + (dataLayerName)] = function () {
58-
// eslint-disable-next-line
59-
(window as any)[dataLayerName].push(arguments)
125+
schema: import.meta.dev ? GoogleAnalyticsOptions : undefined,
126+
scriptOptions: {
127+
use: () => {
128+
return {
129+
dataLayer: w[dataLayerName] as DataLayer,
130+
gtag: w.gtag as DataLayer,
60131
}
61-
; ((window as any)['gtag-' + (dataLayerName)] as GTag)('js', new Date())
62-
; ((window as any)['gtag-' + (dataLayerName)] as GTag)('config', (options?.id))
63132
},
64-
}), _options)
133+
performanceMarkFeature: 'nuxt-third-parties-ga',
134+
tagPriority: 1,
135+
},
136+
clientInit: import.meta.server
137+
? undefined
138+
: () => {
139+
w[dataLayerName] = w[dataLayerName] || []
140+
w.gtag = function () {
141+
// eslint-disable-next-line
142+
w[dataLayerName].push(arguments)
143+
}
144+
// eslint-disable-next-line
145+
// @ts-ignore
146+
_options?.onBeforeGtagStart?.(w.gtag)
147+
gtag('js', new Date())
148+
gtag('config', (options?.id))
149+
},
150+
}
151+
}, _options)
65152
}
153+
154+
useScriptGoogleAnalytics({
155+
scriptOptions: {
156+
trigger: 'manual',
157+
},
158+
})

0 commit comments

Comments
 (0)
Please sign in to comment.