@owlmeans/web-gtm 0.1.18-rc.22 → 0.1.18-rc.24

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -6,7 +6,7 @@ This package ships embedded agent skills under `agent-meta/`. After installing y
6
6
  your project's skill store (`.agents/skills/`):
7
7
 
8
8
  ```sh
9
- npx @owlmeans/agent-skills@^0.1.18-rc.28
9
+ npx @owlmeans/agent-skills@^0.1.18-rc.31
10
10
  ```
11
11
 
12
12
  The embedded files are version-matched to this package release. Do not edit them
@@ -1,8 +1,8 @@
1
1
  {
2
2
  "schemaVersion": 2,
3
3
  "package": "@owlmeans/web-gtm",
4
- "version": "0.1.18-rc.22",
5
- "generatedAt": "2026-09-17T08:18:52.131Z",
4
+ "version": "0.1.18-rc.24",
5
+ "generatedAt": "2026-09-21T21:54:22.945Z",
6
6
  "canonicalRepo": "https://github.com/owlmeans/common",
7
7
  "entries": [
8
8
  {
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: web-gtm
3
- description: How to use @owlmeans/web-gtm — the Google Tag Manager head snippet that declares Consent Mode defaults before the container loads, the noscript frame, and the script-side loader for a host that cannot edit its own HTML. Auto-invoked when adding a tag manager to a page, importing gtmHeadScript, gtmNoscriptFrame or loadGtm, or debugging why a tag ignores a stored consent decision.
3
+ description: How to use @owlmeans/web-gtm — the Google tag head snippet for every Google id (Tag Manager GTM-, GA4 G-, Google tag GT-, Ads AW-, Floodlight DC-) that declares Consent Mode defaults before any loader runs, the id validator, the CSP host lists, the cookie-policy disclosure for a tag, the noscript frame, and the script-side loader for a host that cannot edit its own HTML. Auto-invoked when adding a Google tag or tag manager to a page, importing googleTagHeadScript, isGoogleTagId, GOOGLE_TAG_CSP_SOURCES, googleTagServices, gtmHeadScript, gtmNoscriptFrame or loadGtm, or debugging why a tag ignores a stored consent decision or is blocked by CSP.
4
4
  user-invocable: false
5
5
  ---
6
6
  <!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->
@@ -8,75 +8,147 @@ user-invocable: false
8
8
  # @owlmeans/web-gtm
9
9
 
10
10
  **Layer:** Web
11
- **Install:** `"@owlmeans/web-gtm": "^0.1.18-rc.22"` in `dependencies`
11
+ **Install:** `"@owlmeans/web-gtm": "^0.1.18-rc.24"` in `dependencies`
12
12
 
13
- The tag-manager half of the consent set. It emits **strings**, not components, and it holds no
13
+ The tag half of the consent set. It emits **strings and data**, not components, and it holds no
14
14
  state — the decision lives in `@owlmeans/consent`, which this package reads through
15
15
  `consentBootstrapScript` and `consentStore`.
16
16
 
17
17
  ## The one idea: order
18
18
 
19
- Google Tag Manager decides what a tag may do from the consent state present **when the container
20
- loads**. A React bundle cannot get there first: by the time an island mounts, `gtm.js` has been
21
- running for hundreds of milliseconds and has already decided. A site whose defaults arrive after
22
- the container is not configured differently — it is *unconfigured for the window that matters*, and
23
- nothing in the page reports it.
19
+ A Google tag — the Tag Manager container or gtag.js alike — decides what it may do from the
20
+ consent state present **when it loads**. A React bundle cannot get there first: by the time an
21
+ island mounts, the tag has been running for hundreds of milliseconds and has already decided. A
22
+ site whose defaults arrive after the loader is not configured differently — it is *unconfigured
23
+ for the window that matters*, and nothing in the page reports it.
24
24
 
25
- So `gtmHeadScript` emits the consent bootstrap and then the container, in that order, as one
25
+ So every head snippet here emits the consent bootstrap first and the loader after it, as ONE
26
26
  inline script. Everything else in this package exists to serve that.
27
27
 
28
28
  ## Key Exports
29
29
 
30
30
  | Export | Description |
31
31
  |--------|-------------|
32
- | `gtmHeadScript(opts)` | The inline `<head>` snippet: consent defaults, stored decision, then the container |
32
+ | `googleTagHeadScript(opts)` | The inline `<head>` script for any Google id: consent bootstrap, ads redaction, then the loader the prefix calls for. **The default for new code** |
33
+ | `isGoogleTagId(id)` / `googleTagKind(id)` | Whether an id is loadable, and whether it takes `gtm` (container) or `gtag` (gtag.js); `null` for anything else |
34
+ | `GoogleTagOptions` / `GoogleTagKind` | `ConsentOptions` plus `id` and optional `dataLayerName`; `'gtm' \| 'gtag'` |
35
+ | `GOOGLE_TAG_CSP_SOURCES` | The hosts GA4, Tag Manager and Google Ads need in `script-src`, `connect-src` and `img-src` (7, frozen) |
36
+ | `GOOGLE_TAG_FRAME_SOURCES` | The hosts they frame, for `frame-src`: `https://www.googletagmanager.com`, `https://td.doubleclick.net` |
37
+ | `googleTagServices(id)` | The `ConsentService[]` a cookie policy discloses for that tag — pass to `CookiePolicy`'s `services` |
38
+ | `gtmHeadScript(opts)` | The container-only snippet: consent defaults, stored decision, then `gtm.js` |
33
39
  | `gtmNoscriptFrame(opts)` | The hidden `<noscript>` iframe, for the top of `<body>` |
34
40
  | `loadGtm(opts)` | Script-side container load, for a host that cannot emit into its own head |
35
41
  | `GtmOptions` | `ConsentOptions` plus `id` (e.g. `GTM-XXXXXXX`) and optional `dataLayerName` |
36
42
 
43
+ ## Ids
44
+
45
+ `isGoogleTagId` accepts exactly `GTM-` + 4–12, or `G-` / `GT-` / `AW-` / `DC-` + 4–16, upper-case
46
+ letters and digits. It is strict on purpose: the id is typed into a settings form and ends up in
47
+ an inline script and a script URL, and a value it accepts cannot carry a quote, a tag or a second
48
+ query parameter — so **validate with it where the id is stored**, not only where it is emitted.
49
+ Lower case is rejected rather than folded; normalise in the form if you want to be forgiving.
50
+ `UA-` (Universal Analytics, retired) is rejected: it would promise measurement that never comes.
51
+
52
+ | Prefix | Kind | Loader |
53
+ |---|---|---|
54
+ | `GTM-` | `gtm` | `gtm.js` — Google's container IIFE |
55
+ | `G-` GA4, `GT-` Google tag, `AW-` Google Ads, `DC-` Floodlight | `gtag` | `gtag/js`, then `js` and `config` |
56
+
57
+ ## `googleTagHeadScript` — what it emits
58
+
59
+ 1. `consentBootstrapScript(opts)` — `consent/default` (everything denied except
60
+ `security_storage`) and, for a returning visitor, `consent/update` from the stored record.
61
+ 2. `set ads_data_redaction true` and `set url_passthrough false` — both have to precede the tag's
62
+ `config`. Redaction strips ad-click ids and goes cookieless while `ad_storage` is denied.
63
+ 3. The loader. For `gtag`: a queue function (published as `window.gtag` only when nothing else
64
+ owns it, so app code can send events), `js`, `config`, and the gtag.js `<script async>`
65
+ element created from the inline script — one inline script rather than Google's two elements,
66
+ so a build stamps one thing. The element carries id `owl-gtag-<id>`, so running the snippet
67
+ twice configures the tag once instead of double-counting page views.
68
+
69
+ An **invalid id yields the consent bootstrap alone** — a mistyped tag must never cost a page its
70
+ consent defaults. So a host may stamp `googleTagHeadScript({ id: configured })` unconditionally,
71
+ or stamp `consentBootstrapScript()` when no tag is configured; both are correct.
72
+
73
+ **The output is safe to place inline in HTML as-is.** JSON encoding keeps configured values inside
74
+ their string literals, but the HTML parser ends a script element at the first `</script` wherever
75
+ it sits, so every `</` and `<!--` in the output is backslash-escaped (`<\/`, `<\!--` — JavaScript
76
+ reads them unchanged). `gtmHeadScript` predates this and does not escape; prefer
77
+ `googleTagHeadScript` wherever category keys or a storage key come from configuration.
78
+
37
79
  ## Stamping it
38
80
 
39
81
  ```typescript
40
- import { gtmHeadScript, gtmNoscriptFrame } from '@owlmeans/web-gtm'
82
+ import { googleTagHeadScript } from '@owlmeans/web-gtm'
41
83
 
42
- const opts = { id: 'GTM-XXXXXXX' }
43
- const head = gtmHeadScript(opts) // inline <script> content for <head>, first
44
- const frame = gtmNoscriptFrame(opts) // <noscript> content for the top of <body>
84
+ const head = googleTagHeadScript({ id: 'G-XXXXXXXXXX' }) // inline <script> content, first in <head>
45
85
  ```
46
86
 
47
- The snippet is stamped **from HTML**, never from the application bundle. How each surface does it:
48
-
49
- - a Vite app — a `transformIndexHtml` plugin substituting the two markers, so the snippet cannot
50
- drift from the package;
51
- - an Astro site — `owlHeadScripts()` from `@owlmeans/astro`, `set:html` in the base layout.
52
-
53
- A surface that runs no container of its own stamps only `consentBootstrapScript()` from
54
- `@owlmeans/consent` — that is the case for the bundler-generated `index.html` of a generated
55
- application, which carries the consent bootstrap and no tag manager. The bootstrap and this
56
- snippet are separate stampings: adding a container means adding `gtmHeadScript` /
57
- `gtmNoscriptFrame` beside it.
58
-
59
- `gtmHeadScript` also **reads the stored decision** and pushes `consent/update` before the
60
- container, so a returning visitor's tags are not denied for the first paint of every page. That
61
- read is why the same `ConsentOptions` (categories, `storageKey`) must be passed here and to the
62
- dialog: two different category sets in one page mean the snippet and the component disagree about
63
- what was asked.
87
+ The snippet is stamped **from HTML**, never from the application bundle:
88
+
89
+ - a Vite app — a `transformIndexHtml` plugin substituting a marker, so the snippet cannot drift
90
+ from the package;
91
+ - an Astro site — `owlHeadScripts()` from `@owlmeans/astro`, `set:html` in the base layout;
92
+ - a **generated Viable app** — its Rollup build writes `index.html` and puts
93
+ `googleTagHeadScript({ id })` in the `<head>` when the project owner has set a Google tag
94
+ (`BRANDING_GOOGLE_TAG`), and `consentBootstrapScript()` otherwise. The tag is attached in
95
+ **preview and production** alike; the consent default is first in both.
96
+
97
+ The snippet **reads the stored decision**, so the same `ConsentOptions` (categories, `storageKey`)
98
+ must be passed here and to the dialog: two category sets in one page mean the snippet and the
99
+ component disagree about what was asked.
100
+
101
+ ## Content Security Policy
102
+
103
+ A page served with a CSP must allow the tag's hosts, or the loader is blocked and nothing on the
104
+ page says so.
105
+
106
+ - `GOOGLE_TAG_CSP_SOURCES` goes into `script-src`, `connect-src` and `img-src` — one list for all
107
+ three, folded from Google's CSP guide (developers.google.com/tag-platform/security/guides/csp):
108
+ `*.googletagmanager.com`, `*.google-analytics.com`, `*.g.doubleclick.net`, `ad.doubleclick.net`,
109
+ `www.googleadservices.com`, `pagead2.googlesyndication.com`, `*.google.com`. Each is
110
+ `https://` + optional `*.` + a dotted host, the only shape the Viable publisher's source filter
111
+ admits, and few enough to fit its per-slot cap. Google's country domains (`google.<TLD>`) cannot
112
+ be expressed in that shape; what is lost is a remarketing ping, never the tag.
113
+ - `GOOGLE_TAG_FRAME_SOURCES` goes into `frame-src`.
114
+ - The inline head script itself is covered by the document's own script hash — the Viable
115
+ publisher derives `'sha256-…'` from the document it sends — so nothing else is needed for it.
116
+ - **Tag Manager Custom HTML tags do not run under a hash-based CSP**: they inject inline scripts
117
+ no hash names, and `'unsafe-inline'` is not an option. Custom JavaScript variables need
118
+ `'unsafe-eval'` and fail the same way. Build a container for such a page from Google's
119
+ **built-in tag templates** (GA4, Google Ads, Floodlight, Conversion Linker) and Community
120
+ Gallery templates, which load from the allowed hosts.
121
+
122
+ ## Disclosing it
123
+
124
+ `googleTagServices(id)` returns what the cookie policy lists under each category, read off the
125
+ prefix — the page knows nothing more:
126
+
127
+ | Id | Entries |
128
+ |---|---|
129
+ | `G-` | Google Analytics — `analytics`; `_ga`, `_ga_<id without G->` |
130
+ | `AW-` | Google Ads — `marketing`; `_gcl_au`, `_gcl_aw` |
131
+ | `DC-` | Floodlight — `marketing`; `_gcl_au`, `_gcl_dc` |
132
+ | `GTM-`, `GT-` | one `analytics` AND one `marketing` entry, worded as "configured in the container" / "for it at Google" — the policy may not claim less than the tag can do |
133
+ | invalid | `[]` — it loads nothing, so it discloses nothing |
134
+
135
+ Pass them to `CookiePolicy` (`services`) wherever the tag is stamped; a generated Viable app's
136
+ cookie page does so when a Google tag is set. The strings are English data, not translation keys.
64
137
 
65
138
  ## Gotchas
66
139
 
67
- - **The container id and queue name are injected as data, never interpolated raw.** Both come from
68
- configuration, and configuration reaches these functions as a string. `gtmHeadScript` JSON-encodes
69
- them, so a quote inside an id is escaped rather than closing the literal and turning the rest into
70
- executable script; `gtmNoscriptFrame` URL-encodes the id so it cannot break out of the attribute.
71
- Never build either string by hand.
72
- - **`dataLayerName` is for a page running more than one container.** It is passed through to the
73
- container the way Google's own snippet does (`&l=` when it is not `dataLayer`); leave it unset
74
- otherwise, or tags looking at the default queue see nothing.
140
+ - **Consent Mode speaks on `window.dataLayer`.** The bootstrap and the dialog's later
141
+ `consent/update` both push there, so a tag given another `dataLayerName` never hears a consent
142
+ command. Leave `dataLayerName` unset on any consent-gated page; it exists for a page running a
143
+ second, separately-consented container. `googleTagHeadScript` falls back to `dataLayer` when the
144
+ name is not a plain identifier.
145
+ - **Ids and queue names are injected as data, never interpolated raw.** `gtmHeadScript` and
146
+ `googleTagHeadScript` JSON-encode them; `gtmNoscriptFrame` URL-encodes the id so it cannot break
147
+ out of the attribute. Never build either string by hand.
75
148
  - **`loadGtm` is the fallback, not the default.** It is for a single-page app whose HTML is not
76
149
  yours to edit. It still pushes the defaults first (through `consentStore.init`) and refuses to
77
150
  load a second time — it marks its own `<script>` element with an id derived from the container —
78
- but it runs after the bundle, which is exactly the window the head snippet closes. Prefer the
79
- head snippet wherever the document can be edited.
151
+ but it runs after the bundle, which is exactly the window the head snippet closes.
80
152
  - **A second `consent/default` after a tag has loaded can WIDEN what was already narrowed**, so the
81
153
  bootstrap is idempotent through a window flag. A page may therefore carry the call twice — once
82
154
  inline, once from the bundle that mounts the dialog — without harm. Do not defeat the flag.
@@ -85,12 +157,13 @@ what was asked.
85
157
 
86
158
  ## Depends On
87
159
 
88
- - `@owlmeans/consent` — `consentBootstrapScript`, `consentStore`, `ConsentOptions`, the category
89
- model and the Consent Mode signal mapping
160
+ - `@owlmeans/consent` — `consentBootstrapScript`, `consentStore`, `ConsentOptions`,
161
+ `ConsentService`, the category keys and the Consent Mode signal mapping
90
162
 
91
163
  ## Related
92
164
 
93
165
  - `consent` — categories, the storage record and its migration, Consent Mode v2 signalling, and the
94
166
  ordering rule this package implements
95
- - `web-consent` — the dialog and the cookie-policy page that produce the decision
96
- - `astro` — `owlHeadScripts()`, which composes both strings for an Astro layout
167
+ - `web-consent` — the dialog and the cookie-policy page (`services`) that produce and disclose the
168
+ decision
169
+ - `astro` — `owlHeadScripts()`, which composes the head strings for an Astro layout
package/build/index.d.ts CHANGED
@@ -1,4 +1,4 @@
1
- import type { ConsentOptions } from '@owlmeans/consent';
1
+ import type { ConsentOptions, ConsentService } from '@owlmeans/consent';
2
2
  export interface GtmOptions extends ConsentOptions {
3
3
  /** Container id, e.g. `GTM-XXXXXXX`. */
4
4
  id: string;
@@ -27,4 +27,77 @@ export declare const gtmNoscriptFrame: (opts: GtmOptions) => string;
27
27
  * a second time.
28
28
  */
29
29
  export declare const loadGtm: (opts: GtmOptions) => void;
30
+ /**
31
+ * Which loader an id takes: `gtm` is the Tag Manager container (`gtm.js`), `gtag` the Google tag
32
+ * (`gtag.js`) — Google Analytics 4 (`G-`), a Google tag (`GT-`), Google Ads (`AW-`) and
33
+ * Floodlight (`DC-`).
34
+ */
35
+ export type GoogleTagKind = 'gtm' | 'gtag';
36
+ /** Whether `id` is a Tag Manager container or Google tag id this package can load. */
37
+ export declare const isGoogleTagId: (id: string) => boolean;
38
+ /** The loader `id` takes, or `null` when it is not a loadable id at all. */
39
+ export declare const googleTagKind: (id: string) => GoogleTagKind | null;
40
+ export interface GoogleTagOptions extends ConsentOptions {
41
+ /** `GTM-…`, `G-…`, `GT-…`, `AW-…` or `DC-…` — see {@link isGoogleTagId}. */
42
+ id: string;
43
+ /**
44
+ * The queue name, when a page runs more than one tag. Consent Mode from `@owlmeans/consent` —
45
+ * the bootstrap AND the dialog's later updates — always speaks on `window.dataLayer`, so a tag
46
+ * given another queue never hears a consent command. Leave it unset on a consent-gated page.
47
+ */
48
+ dataLayerName?: string;
49
+ }
50
+ /**
51
+ * The one inline `<head>` script for a Google tag of any kind: the consent bootstrap FIRST, then
52
+ * ads redaction, then the loader the id's prefix calls for — the Tag Manager container for `GTM-`,
53
+ * gtag.js with `js` and `config` for `G-`, `GT-`, `AW-` and `DC-`.
54
+ *
55
+ * The order is the rule {@link gtmHeadScript} exists for, and it holds for gtag.js just the same:
56
+ * a tag decides what it may do from the consent state present when it loads. The bootstrap
57
+ * declares everything denied and applies any stored decision in the same turn, so a returning
58
+ * visitor's tag starts granted and a new visitor's starts cookieless.
59
+ *
60
+ * An id that is not a loadable id ({@link isGoogleTagId}) yields the consent bootstrap alone — a
61
+ * page must never lose its consent defaults because someone mistyped a tag. The result is safe to
62
+ * place inline in HTML as-is: `</` and `<!--` inside any configured value are escaped.
63
+ */
64
+ export declare const googleTagHeadScript: (opts: GoogleTagOptions) => string;
65
+ /**
66
+ * The hosts a page running a Google tag has to allow in `script-src`, `connect-src` and
67
+ * `img-src`, for Google Analytics 4, Tag Manager and Google Ads together.
68
+ *
69
+ * Taken from Google's CSP guide (developers.google.com/tag-platform/security/guides/csp) and
70
+ * folded into one list, because the platform adds one list to all three directives:
71
+ *
72
+ * - `*.googletagmanager.com` — gtm.js and gtag/js (`www.`), and their measurement pings;
73
+ * - `*.google-analytics.com` — GA4 collection (`region1.`, `www.`);
74
+ * - `*.g.doubleclick.net` — GA4 with Google signals and Ads (`stats.g.`, `googleads.g.`);
75
+ * - `ad.doubleclick.net` — Ads and Floodlight conversions;
76
+ * - `www.googleadservices.com` — the Ads conversion script;
77
+ * - `pagead2.googlesyndication.com` — Ads and GA4-with-ads pings;
78
+ * - `*.google.com` — `www.google.com` (the Ads script, consent-mode pings), `adservice.`, and the
79
+ * `analytics.google.com` collection endpoints.
80
+ *
81
+ * Every entry is an `https://` scheme, an optional `*.` label and a dotted host — the only shape
82
+ * the publisher's CSP filter lets through — and there are few enough to stay inside its per-slot
83
+ * cap. Google's country domains (`google.<TLD>`) cannot be named in that shape and are left out:
84
+ * what is lost is a remarketing ping from visitors on those domains, never the tag itself.
85
+ */
86
+ export declare const GOOGLE_TAG_CSP_SOURCES: readonly string[];
87
+ /**
88
+ * The hosts a Google tag frames: Tag Manager's service-worker and preview frames, and the Ads
89
+ * remarketing frame. For `frame-src`, which otherwise stays `'none'`.
90
+ */
91
+ export declare const GOOGLE_TAG_FRAME_SOURCES: readonly string[];
92
+ /**
93
+ * What a Google tag discloses on the cookie policy, for `CookiePolicy`'s `services`.
94
+ *
95
+ * Read off the id's prefix, because that is all the page knows: `G-` is Google Analytics 4
96
+ * (`_ga`, and `_ga_<id without G->` which carries the session), `AW-` Google Ads, `DC-` Floodlight.
97
+ * A `GTM-` container and a `GT-` Google tag route to whatever their owner configured at Google,
98
+ * so both are disclosed as an analytics AND an advertising entry, worded as configured there —
99
+ * the policy may not claim less than the tag can do. An invalid id discloses nothing, matching
100
+ * {@link googleTagHeadScript}, which loads nothing for it.
101
+ */
102
+ export declare const googleTagServices: (id: string) => ConsentService[];
30
103
  //# sourceMappingURL=index.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAA;AAEvD,MAAM,WAAW,UAAW,SAAQ,cAAc;IAChD,wCAAwC;IACxC,EAAE,EAAE,MAAM,CAAA;IACV,gEAAgE;IAChE,aAAa,CAAC,EAAE,MAAM,CAAA;CACvB;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,aAAa,SAAU,UAAU,KAAG,MAWhD,CAAA;AAED,6CAA6C;AAC7C,eAAO,MAAM,gBAAgB,SAAU,UAAU,KAAG,MAEsB,CAAA;AAE1E;;;;;;GAMG;AACH,eAAO,MAAM,OAAO,SAAU,UAAU,KAAG,IAkB1C,CAAA"}
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAA;AAEvE,MAAM,WAAW,UAAW,SAAQ,cAAc;IAChD,wCAAwC;IACxC,EAAE,EAAE,MAAM,CAAA;IACV,gEAAgE;IAChE,aAAa,CAAC,EAAE,MAAM,CAAA;CACvB;AAYD;;;;;;;;;;GAUG;AACH,eAAO,MAAM,aAAa,SAAU,UAAU,KAAG,MACoD,CAAA;AAErG,6CAA6C;AAC7C,eAAO,MAAM,gBAAgB,SAAU,UAAU,KAAG,MAEsB,CAAA;AAE1E;;;;;;GAMG;AACH,eAAO,MAAM,OAAO,SAAU,UAAU,KAAG,IAkB1C,CAAA;AAED;;;;GAIG;AACH,MAAM,MAAM,aAAa,GAAG,KAAK,GAAG,MAAM,CAAA;AAc1C,sFAAsF;AACtF,eAAO,MAAM,aAAa,OAAQ,MAAM,KAAG,OACO,CAAA;AAElD,4EAA4E;AAC5E,eAAO,MAAM,aAAa,OAAQ,MAAM,KAAG,aAAa,GAAG,IACS,CAAA;AAEpE,MAAM,WAAW,gBAAiB,SAAQ,cAAc;IACtD,4EAA4E;IAC5E,EAAE,EAAE,MAAM,CAAA;IACV;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,CAAA;CACvB;AAyDD;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,mBAAmB,SAAU,gBAAgB,KAAG,MAU5D,CAAA;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,sBAAsB,EAAE,SAAS,MAAM,EAQlD,CAAA;AAEF;;;GAGG;AACH,eAAO,MAAM,wBAAwB,EAAE,SAAS,MAAM,EAGpD,CAAA;AAkBF;;;;;;;;;GASG;AACH,eAAO,MAAM,iBAAiB,OAAQ,MAAM,KAAG,cAAc,EA8C5D,CAAA"}
package/build/index.js CHANGED
@@ -1,4 +1,12 @@
1
- import { consentBootstrapScript, consentStore } from '@owlmeans/consent';
1
+ import { CONSENT_ANALYTICS, CONSENT_MARKETING, consentBootstrapScript, consentStore, } from '@owlmeans/consent';
2
+ /** Google's own container IIFE, the id and queue name injected as JSON data. */
3
+ const gtmContainerScript = (layer, id) => `(function(w,d,s,l,i){w[l]=w[l]||[];` +
4
+ `w[l].push({'gtm.start':new Date().getTime(),event:'gtm.js'});` +
5
+ `var f=d.getElementsByTagName(s)[0],j=d.createElement(s),` +
6
+ `dl=l!='dataLayer'?'&l='+l:'';j.async=true;` +
7
+ `j.src='https://www.googletagmanager.com/gtm.js?id='+i+dl;` +
8
+ `f.parentNode.insertBefore(j,f)})` +
9
+ `(window,document,'script',${JSON.stringify(layer)},${JSON.stringify(id)})`;
2
10
  /**
3
11
  * The inline `<head>` snippet, consent first and the container second.
4
12
  *
@@ -10,17 +18,7 @@ import { consentBootstrapScript, consentStore } from '@owlmeans/consent';
10
18
  *
11
19
  * Emit this into the document head, above everything else, as an inline script.
12
20
  */
13
- export const gtmHeadScript = (opts) => {
14
- const layer = opts.dataLayerName ?? 'dataLayer';
15
- return `${consentBootstrapScript(opts)};` +
16
- `(function(w,d,s,l,i){w[l]=w[l]||[];` +
17
- `w[l].push({'gtm.start':new Date().getTime(),event:'gtm.js'});` +
18
- `var f=d.getElementsByTagName(s)[0],j=d.createElement(s),` +
19
- `dl=l!='dataLayer'?'&l='+l:'';j.async=true;` +
20
- `j.src='https://www.googletagmanager.com/gtm.js?id='+i+dl;` +
21
- `f.parentNode.insertBefore(j,f)})` +
22
- `(window,document,'script',${JSON.stringify(layer)},${JSON.stringify(opts.id)})`;
23
- };
21
+ export const gtmHeadScript = (opts) => `${consentBootstrapScript(opts)};${gtmContainerScript(opts.dataLayerName ?? 'dataLayer', opts.id)}`;
24
22
  /** The `<noscript>` iframe, for the body. */
25
23
  export const gtmNoscriptFrame = (opts) => `<iframe src="https://www.googletagmanager.com/ns.html?id=${encodeURIComponent(opts.id)}"` +
26
24
  ` height="0" width="0" style="display:none;visibility:hidden"></iframe>`;
@@ -49,4 +47,175 @@ export const loadGtm = (opts) => {
49
47
  + (layer !== 'dataLayer' ? `&l=${encodeURIComponent(layer)}` : '');
50
48
  document.head.appendChild(script);
51
49
  };
50
+ /**
51
+ * The id shapes Google issues today, and nothing else.
52
+ *
53
+ * Deliberately strict — upper case, a known prefix, a bounded run of letters and digits — because
54
+ * the id is typed by a person into a settings form and ends up inside an inline script and a
55
+ * script URL. A value this pattern accepts cannot carry a quote, a tag or a second parameter, so
56
+ * the check is what makes it safe to store, not only to emit. `UA-` is not here: Universal
57
+ * Analytics stopped processing data in 2024, and accepting its ids would promise measurement that
58
+ * never arrives.
59
+ */
60
+ const GOOGLE_TAG_ID = /^(GTM-[A-Z0-9]{4,12}|(G|GT|AW|DC)-[A-Z0-9]{4,16})$/;
61
+ /** Whether `id` is a Tag Manager container or Google tag id this package can load. */
62
+ export const isGoogleTagId = (id) => typeof id === 'string' && GOOGLE_TAG_ID.test(id);
63
+ /** The loader `id` takes, or `null` when it is not a loadable id at all. */
64
+ export const googleTagKind = (id) => !isGoogleTagId(id) ? null : id.startsWith('GTM-') ? 'gtm' : 'gtag';
65
+ /** A queue name has to be a plain identifier: it becomes `window[name]` in the emitted script. */
66
+ const JS_IDENTIFIER = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
67
+ const layerOf = (opts) => opts.dataLayerName != null && JS_IDENTIFIER.test(opts.dataLayerName)
68
+ ? opts.dataLayerName
69
+ : 'dataLayer';
70
+ /**
71
+ * Make a generated script safe to place between `<script>` and `</script>`.
72
+ *
73
+ * JSON encoding keeps a value inside its string literal, but the HTML parser does not read
74
+ * JavaScript: it ends the element at the first `</script` it meets, wherever it sits, and a
75
+ * `<!--` can switch it into a state where the real closing tag is swallowed. Both sequences can
76
+ * only appear inside the JSON-encoded values here — category keys, a storage key, a queue name —
77
+ * so each gets a backslash that JavaScript reads as nothing (`\/` is `/`, `\!` is `!`).
78
+ */
79
+ const inlineSafe = (script) => script.replace(/<\//g, '<\\/').replace(/<!--/g, '<\\!--');
80
+ /**
81
+ * Ads data redaction on, URL passthrough off — before any loader runs.
82
+ *
83
+ * `ads_data_redaction` makes an Ads or Floodlight tag strip ad-click identifiers and send its
84
+ * requests through a cookieless domain while `ad_storage` is denied. `url_passthrough` is set to
85
+ * its default explicitly so that nothing configured later on the page can switch on decorating
86
+ * links with click ids for a visitor who refused marketing storage. Google reads both only when
87
+ * they are set ahead of the tag's `config`.
88
+ */
89
+ const redactionScript = (layer) => `(function(w,l){w[l]=w[l]||[];function g(){w[l].push(arguments)}` +
90
+ `g('set','ads_data_redaction',true);g('set','url_passthrough',false)})` +
91
+ `(window,${JSON.stringify(layer)})`;
92
+ /**
93
+ * Google's gtag.js snippet as one inline script: the queue function, `js` and `config`, then the
94
+ * library requested from here rather than from a second `<script src>` element.
95
+ *
96
+ * One inline script instead of Google's two elements because the document it lands in is served
97
+ * with a hash-based CSP and stamped by a build that writes one head snippet — a second element
98
+ * would be a second thing to keep in order. The element carries an id derived from the tag, so a
99
+ * page that runs the snippet twice (two stampings, a hot reload) does not configure the tag twice
100
+ * and double-count every page view. `window.gtag` is published only when nothing else owns it, so
101
+ * application code can send its own events.
102
+ */
103
+ const gtagScript = (layer, id) => `(function(w,d,l,i){var m='owl-gtag-'+i;if(d.getElementById(m))return;` +
104
+ `w[l]=w[l]||[];function g(){w[l].push(arguments)}if(!w.gtag)w.gtag=g;` +
105
+ `g('js',new Date());g('config',i);` +
106
+ `var j=d.createElement('script');j.id=m;j.async=true;` +
107
+ `j.src='https://www.googletagmanager.com/gtag/js?id='+encodeURIComponent(i)` +
108
+ `+(l!='dataLayer'?'&l='+encodeURIComponent(l):'');` +
109
+ `(d.head||d.documentElement).appendChild(j)})` +
110
+ `(window,document,${JSON.stringify(layer)},${JSON.stringify(id)})`;
111
+ /**
112
+ * The one inline `<head>` script for a Google tag of any kind: the consent bootstrap FIRST, then
113
+ * ads redaction, then the loader the id's prefix calls for — the Tag Manager container for `GTM-`,
114
+ * gtag.js with `js` and `config` for `G-`, `GT-`, `AW-` and `DC-`.
115
+ *
116
+ * The order is the rule {@link gtmHeadScript} exists for, and it holds for gtag.js just the same:
117
+ * a tag decides what it may do from the consent state present when it loads. The bootstrap
118
+ * declares everything denied and applies any stored decision in the same turn, so a returning
119
+ * visitor's tag starts granted and a new visitor's starts cookieless.
120
+ *
121
+ * An id that is not a loadable id ({@link isGoogleTagId}) yields the consent bootstrap alone — a
122
+ * page must never lose its consent defaults because someone mistyped a tag. The result is safe to
123
+ * place inline in HTML as-is: `</` and `<!--` inside any configured value are escaped.
124
+ */
125
+ export const googleTagHeadScript = (opts) => {
126
+ const bootstrap = consentBootstrapScript(opts);
127
+ const kind = googleTagKind(opts.id);
128
+ if (kind == null) {
129
+ return inlineSafe(bootstrap);
130
+ }
131
+ const layer = layerOf(opts);
132
+ const loader = kind === 'gtm' ? gtmContainerScript(layer, opts.id) : gtagScript(layer, opts.id);
133
+ return inlineSafe(`${bootstrap};${redactionScript(layer)};${loader}`);
134
+ };
135
+ /**
136
+ * The hosts a page running a Google tag has to allow in `script-src`, `connect-src` and
137
+ * `img-src`, for Google Analytics 4, Tag Manager and Google Ads together.
138
+ *
139
+ * Taken from Google's CSP guide (developers.google.com/tag-platform/security/guides/csp) and
140
+ * folded into one list, because the platform adds one list to all three directives:
141
+ *
142
+ * - `*.googletagmanager.com` — gtm.js and gtag/js (`www.`), and their measurement pings;
143
+ * - `*.google-analytics.com` — GA4 collection (`region1.`, `www.`);
144
+ * - `*.g.doubleclick.net` — GA4 with Google signals and Ads (`stats.g.`, `googleads.g.`);
145
+ * - `ad.doubleclick.net` — Ads and Floodlight conversions;
146
+ * - `www.googleadservices.com` — the Ads conversion script;
147
+ * - `pagead2.googlesyndication.com` — Ads and GA4-with-ads pings;
148
+ * - `*.google.com` — `www.google.com` (the Ads script, consent-mode pings), `adservice.`, and the
149
+ * `analytics.google.com` collection endpoints.
150
+ *
151
+ * Every entry is an `https://` scheme, an optional `*.` label and a dotted host — the only shape
152
+ * the publisher's CSP filter lets through — and there are few enough to stay inside its per-slot
153
+ * cap. Google's country domains (`google.<TLD>`) cannot be named in that shape and are left out:
154
+ * what is lost is a remarketing ping from visitors on those domains, never the tag itself.
155
+ */
156
+ export const GOOGLE_TAG_CSP_SOURCES = Object.freeze([
157
+ 'https://*.googletagmanager.com',
158
+ 'https://*.google-analytics.com',
159
+ 'https://*.g.doubleclick.net',
160
+ 'https://ad.doubleclick.net',
161
+ 'https://www.googleadservices.com',
162
+ 'https://pagead2.googlesyndication.com',
163
+ 'https://*.google.com',
164
+ ]);
165
+ /**
166
+ * The hosts a Google tag frames: Tag Manager's service-worker and preview frames, and the Ads
167
+ * remarketing frame. For `frame-src`, which otherwise stays `'none'`.
168
+ */
169
+ export const GOOGLE_TAG_FRAME_SOURCES = Object.freeze([
170
+ 'https://www.googletagmanager.com',
171
+ 'https://td.doubleclick.net',
172
+ ]);
173
+ const GOOGLE = 'Google LLC';
174
+ const GOOGLE_PRIVACY = 'https://policies.google.com/privacy';
175
+ const analyticsService = (name, purpose, cookies) => ({
176
+ name, provider: GOOGLE, category: CONSENT_ANALYTICS, purpose, cookies, privacyHref: GOOGLE_PRIVACY,
177
+ });
178
+ const adsService = (name, purpose, cookies) => ({
179
+ name, provider: GOOGLE, category: CONSENT_MARKETING, purpose, cookies, privacyHref: GOOGLE_PRIVACY,
180
+ });
181
+ const UNTIL_ANALYTICS = 'Until analytics cookies are accepted it sets no cookies and sends only '
182
+ + 'cookieless measurement signals.';
183
+ const UNTIL_MARKETING = 'Until marketing cookies are accepted it sets no cookies and ad click '
184
+ + 'identifiers are redacted.';
185
+ /**
186
+ * What a Google tag discloses on the cookie policy, for `CookiePolicy`'s `services`.
187
+ *
188
+ * Read off the id's prefix, because that is all the page knows: `G-` is Google Analytics 4
189
+ * (`_ga`, and `_ga_<id without G->` which carries the session), `AW-` Google Ads, `DC-` Floodlight.
190
+ * A `GTM-` container and a `GT-` Google tag route to whatever their owner configured at Google,
191
+ * so both are disclosed as an analytics AND an advertising entry, worded as configured there —
192
+ * the policy may not claim less than the tag can do. An invalid id discloses nothing, matching
193
+ * {@link googleTagHeadScript}, which loads nothing for it.
194
+ */
195
+ export const googleTagServices = (id) => {
196
+ if (!isGoogleTagId(id)) {
197
+ return [];
198
+ }
199
+ const prefix = id.slice(0, id.indexOf('-'));
200
+ switch (prefix) {
201
+ case 'G':
202
+ return [analyticsService('Google Analytics', 'Measures how visitors use the site — pages viewed, time spent, device and approximate '
203
+ + `location — so it can be improved. ${UNTIL_ANALYTICS}`, ['_ga', `_ga_${id.slice(2)}`])];
204
+ case 'AW':
205
+ return [adsService('Google Ads', 'Measures which ads led to a visit or a sign-up, and may add visitors to audiences for '
206
+ + `showing them ads elsewhere. ${UNTIL_MARKETING}`, ['_gcl_au', '_gcl_aw'])];
207
+ case 'DC':
208
+ return [adsService('Google Campaign Manager 360 (Floodlight)', `Measures which ad campaigns led to a visit or a sign-up. ${UNTIL_MARKETING}`, ['_gcl_au', '_gcl_dc'])];
209
+ default: {
210
+ const source = prefix === 'GTM' ? 'Google Tag Manager' : 'Google tag';
211
+ const where = prefix === 'GTM' ? 'in its container' : 'for it at Google';
212
+ return [
213
+ analyticsService(`${source} — analytics`, `Runs the analytics tags configured ${where}, typically Google Analytics. `
214
+ + UNTIL_ANALYTICS, ['_ga', '_ga_*']),
215
+ adsService(`${source} — advertising`, `Runs the advertising tags configured ${where}, typically Google Ads conversion `
216
+ + `tracking and remarketing. ${UNTIL_MARKETING}`, ['_gcl_au', '_gcl_aw']),
217
+ ];
218
+ }
219
+ }
220
+ };
52
221
  //# sourceMappingURL=index.js.map
@@ -1 +1 @@
1
- {"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,sBAAsB,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAA;AAUxE;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,IAAgB,EAAU,EAAE;IACxD,MAAM,KAAK,GAAG,IAAI,CAAC,aAAa,IAAI,WAAW,CAAA;IAE/C,OAAO,GAAG,sBAAsB,CAAC,IAAI,CAAC,GAAG;QACvC,qCAAqC;QACrC,+DAA+D;QAC/D,0DAA0D;QAC1D,4CAA4C;QAC5C,2DAA2D;QAC3D,kCAAkC;QAClC,6BAA6B,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,CAAC,GAAG,CAAA;AACpF,CAAC,CAAA;AAED,6CAA6C;AAC7C,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,IAAgB,EAAU,EAAE,CAC3D,4DAA4D,kBAAkB,CAAC,IAAI,CAAC,EAAE,CAAC,GAAG;IAC1F,wEAAwE,CAAA;AAE1E;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,OAAO,GAAG,CAAC,IAAgB,EAAQ,EAAE;IAChD,IAAI,OAAO,QAAQ,KAAK,WAAW,EAAE,CAAC;QACpC,OAAM;IACR,CAAC;IACD,MAAM,MAAM,GAAG,WAAW,IAAI,CAAC,EAAE,EAAE,CAAA;IACnC,IAAI,QAAQ,CAAC,cAAc,CAAC,MAAM,CAAC,IAAI,IAAI,EAAE,CAAC;QAC5C,OAAM;IACR,CAAC;IACD,6FAA6F;IAC7F,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;IAEvB,MAAM,KAAK,GAAG,IAAI,CAAC,aAAa,IAAI,WAAW,CAAA;IAC/C,MAAM,MAAM,GAAG,QAAQ,CAAC,aAAa,CAAC,QAAQ,CAAC,CAAA;IAC/C,MAAM,CAAC,EAAE,GAAG,MAAM,CAAA;IAClB,MAAM,CAAC,KAAK,GAAG,IAAI,CAAA;IACnB,MAAM,CAAC,GAAG,GAAG,8CAA8C,kBAAkB,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE;UACpF,CAAC,KAAK,KAAK,WAAW,CAAC,CAAC,CAAC,MAAM,kBAAkB,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAA;IACpE,QAAQ,CAAC,IAAI,CAAC,WAAW,CAAC,MAAM,CAAC,CAAA;AACnC,CAAC,CAAA"}
1
+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@owlmeans/web-gtm",
3
- "version": "0.1.18-rc.22",
3
+ "version": "0.1.18-rc.24",
4
4
  "license": "MIT",
5
5
  "type": "module",
6
6
  "scripts": {
@@ -22,7 +22,7 @@
22
22
  }
23
23
  },
24
24
  "dependencies": {
25
- "@owlmeans/consent": "^0.1.18-rc.4"
25
+ "@owlmeans/consent": "^0.1.18-rc.5"
26
26
  },
27
27
  "devDependencies": {
28
28
  "@owlmeans/dep-config": "workspace:*",
package/src/index.ts CHANGED
@@ -1,5 +1,7 @@
1
- import { consentBootstrapScript, consentStore } from '@owlmeans/consent'
2
- import type { ConsentOptions } from '@owlmeans/consent'
1
+ import {
2
+ CONSENT_ANALYTICS, CONSENT_MARKETING, consentBootstrapScript, consentStore,
3
+ } from '@owlmeans/consent'
4
+ import type { ConsentOptions, ConsentService } from '@owlmeans/consent'
3
5
 
4
6
  export interface GtmOptions extends ConsentOptions {
5
7
  /** Container id, e.g. `GTM-XXXXXXX`. */
@@ -8,6 +10,16 @@ export interface GtmOptions extends ConsentOptions {
8
10
  dataLayerName?: string
9
11
  }
10
12
 
13
+ /** Google's own container IIFE, the id and queue name injected as JSON data. */
14
+ const gtmContainerScript = (layer: string, id: string): string =>
15
+ `(function(w,d,s,l,i){w[l]=w[l]||[];` +
16
+ `w[l].push({'gtm.start':new Date().getTime(),event:'gtm.js'});` +
17
+ `var f=d.getElementsByTagName(s)[0],j=d.createElement(s),` +
18
+ `dl=l!='dataLayer'?'&l='+l:'';j.async=true;` +
19
+ `j.src='https://www.googletagmanager.com/gtm.js?id='+i+dl;` +
20
+ `f.parentNode.insertBefore(j,f)})` +
21
+ `(window,document,'script',${JSON.stringify(layer)},${JSON.stringify(id)})`
22
+
11
23
  /**
12
24
  * The inline `<head>` snippet, consent first and the container second.
13
25
  *
@@ -19,18 +31,8 @@ export interface GtmOptions extends ConsentOptions {
19
31
  *
20
32
  * Emit this into the document head, above everything else, as an inline script.
21
33
  */
22
- export const gtmHeadScript = (opts: GtmOptions): string => {
23
- const layer = opts.dataLayerName ?? 'dataLayer'
24
-
25
- return `${consentBootstrapScript(opts)};` +
26
- `(function(w,d,s,l,i){w[l]=w[l]||[];` +
27
- `w[l].push({'gtm.start':new Date().getTime(),event:'gtm.js'});` +
28
- `var f=d.getElementsByTagName(s)[0],j=d.createElement(s),` +
29
- `dl=l!='dataLayer'?'&l='+l:'';j.async=true;` +
30
- `j.src='https://www.googletagmanager.com/gtm.js?id='+i+dl;` +
31
- `f.parentNode.insertBefore(j,f)})` +
32
- `(window,document,'script',${JSON.stringify(layer)},${JSON.stringify(opts.id)})`
33
- }
34
+ export const gtmHeadScript = (opts: GtmOptions): string =>
35
+ `${consentBootstrapScript(opts)};${gtmContainerScript(opts.dataLayerName ?? 'dataLayer', opts.id)}`
34
36
 
35
37
  /** The `<noscript>` iframe, for the body. */
36
38
  export const gtmNoscriptFrame = (opts: GtmOptions): string =>
@@ -63,3 +65,236 @@ export const loadGtm = (opts: GtmOptions): void => {
63
65
  + (layer !== 'dataLayer' ? `&l=${encodeURIComponent(layer)}` : '')
64
66
  document.head.appendChild(script)
65
67
  }
68
+
69
+ /**
70
+ * Which loader an id takes: `gtm` is the Tag Manager container (`gtm.js`), `gtag` the Google tag
71
+ * (`gtag.js`) — Google Analytics 4 (`G-`), a Google tag (`GT-`), Google Ads (`AW-`) and
72
+ * Floodlight (`DC-`).
73
+ */
74
+ export type GoogleTagKind = 'gtm' | 'gtag'
75
+
76
+ /**
77
+ * The id shapes Google issues today, and nothing else.
78
+ *
79
+ * Deliberately strict — upper case, a known prefix, a bounded run of letters and digits — because
80
+ * the id is typed by a person into a settings form and ends up inside an inline script and a
81
+ * script URL. A value this pattern accepts cannot carry a quote, a tag or a second parameter, so
82
+ * the check is what makes it safe to store, not only to emit. `UA-` is not here: Universal
83
+ * Analytics stopped processing data in 2024, and accepting its ids would promise measurement that
84
+ * never arrives.
85
+ */
86
+ const GOOGLE_TAG_ID = /^(GTM-[A-Z0-9]{4,12}|(G|GT|AW|DC)-[A-Z0-9]{4,16})$/
87
+
88
+ /** Whether `id` is a Tag Manager container or Google tag id this package can load. */
89
+ export const isGoogleTagId = (id: string): boolean =>
90
+ typeof id === 'string' && GOOGLE_TAG_ID.test(id)
91
+
92
+ /** The loader `id` takes, or `null` when it is not a loadable id at all. */
93
+ export const googleTagKind = (id: string): GoogleTagKind | null =>
94
+ !isGoogleTagId(id) ? null : id.startsWith('GTM-') ? 'gtm' : 'gtag'
95
+
96
+ export interface GoogleTagOptions extends ConsentOptions {
97
+ /** `GTM-…`, `G-…`, `GT-…`, `AW-…` or `DC-…` — see {@link isGoogleTagId}. */
98
+ id: string
99
+ /**
100
+ * The queue name, when a page runs more than one tag. Consent Mode from `@owlmeans/consent` —
101
+ * the bootstrap AND the dialog's later updates — always speaks on `window.dataLayer`, so a tag
102
+ * given another queue never hears a consent command. Leave it unset on a consent-gated page.
103
+ */
104
+ dataLayerName?: string
105
+ }
106
+
107
+ /** A queue name has to be a plain identifier: it becomes `window[name]` in the emitted script. */
108
+ const JS_IDENTIFIER = /^[A-Za-z_$][A-Za-z0-9_$]*$/
109
+
110
+ const layerOf = (opts: GoogleTagOptions): string =>
111
+ opts.dataLayerName != null && JS_IDENTIFIER.test(opts.dataLayerName)
112
+ ? opts.dataLayerName
113
+ : 'dataLayer'
114
+
115
+ /**
116
+ * Make a generated script safe to place between `<script>` and `</script>`.
117
+ *
118
+ * JSON encoding keeps a value inside its string literal, but the HTML parser does not read
119
+ * JavaScript: it ends the element at the first `</script` it meets, wherever it sits, and a
120
+ * `<!--` can switch it into a state where the real closing tag is swallowed. Both sequences can
121
+ * only appear inside the JSON-encoded values here — category keys, a storage key, a queue name —
122
+ * so each gets a backslash that JavaScript reads as nothing (`\/` is `/`, `\!` is `!`).
123
+ */
124
+ const inlineSafe = (script: string): string =>
125
+ script.replace(/<\//g, '<\\/').replace(/<!--/g, '<\\!--')
126
+
127
+ /**
128
+ * Ads data redaction on, URL passthrough off — before any loader runs.
129
+ *
130
+ * `ads_data_redaction` makes an Ads or Floodlight tag strip ad-click identifiers and send its
131
+ * requests through a cookieless domain while `ad_storage` is denied. `url_passthrough` is set to
132
+ * its default explicitly so that nothing configured later on the page can switch on decorating
133
+ * links with click ids for a visitor who refused marketing storage. Google reads both only when
134
+ * they are set ahead of the tag's `config`.
135
+ */
136
+ const redactionScript = (layer: string): string =>
137
+ `(function(w,l){w[l]=w[l]||[];function g(){w[l].push(arguments)}` +
138
+ `g('set','ads_data_redaction',true);g('set','url_passthrough',false)})` +
139
+ `(window,${JSON.stringify(layer)})`
140
+
141
+ /**
142
+ * Google's gtag.js snippet as one inline script: the queue function, `js` and `config`, then the
143
+ * library requested from here rather than from a second `<script src>` element.
144
+ *
145
+ * One inline script instead of Google's two elements because the document it lands in is served
146
+ * with a hash-based CSP and stamped by a build that writes one head snippet — a second element
147
+ * would be a second thing to keep in order. The element carries an id derived from the tag, so a
148
+ * page that runs the snippet twice (two stampings, a hot reload) does not configure the tag twice
149
+ * and double-count every page view. `window.gtag` is published only when nothing else owns it, so
150
+ * application code can send its own events.
151
+ */
152
+ const gtagScript = (layer: string, id: string): string =>
153
+ `(function(w,d,l,i){var m='owl-gtag-'+i;if(d.getElementById(m))return;` +
154
+ `w[l]=w[l]||[];function g(){w[l].push(arguments)}if(!w.gtag)w.gtag=g;` +
155
+ `g('js',new Date());g('config',i);` +
156
+ `var j=d.createElement('script');j.id=m;j.async=true;` +
157
+ `j.src='https://www.googletagmanager.com/gtag/js?id='+encodeURIComponent(i)` +
158
+ `+(l!='dataLayer'?'&l='+encodeURIComponent(l):'');` +
159
+ `(d.head||d.documentElement).appendChild(j)})` +
160
+ `(window,document,${JSON.stringify(layer)},${JSON.stringify(id)})`
161
+
162
+ /**
163
+ * The one inline `<head>` script for a Google tag of any kind: the consent bootstrap FIRST, then
164
+ * ads redaction, then the loader the id's prefix calls for — the Tag Manager container for `GTM-`,
165
+ * gtag.js with `js` and `config` for `G-`, `GT-`, `AW-` and `DC-`.
166
+ *
167
+ * The order is the rule {@link gtmHeadScript} exists for, and it holds for gtag.js just the same:
168
+ * a tag decides what it may do from the consent state present when it loads. The bootstrap
169
+ * declares everything denied and applies any stored decision in the same turn, so a returning
170
+ * visitor's tag starts granted and a new visitor's starts cookieless.
171
+ *
172
+ * An id that is not a loadable id ({@link isGoogleTagId}) yields the consent bootstrap alone — a
173
+ * page must never lose its consent defaults because someone mistyped a tag. The result is safe to
174
+ * place inline in HTML as-is: `</` and `<!--` inside any configured value are escaped.
175
+ */
176
+ export const googleTagHeadScript = (opts: GoogleTagOptions): string => {
177
+ const bootstrap = consentBootstrapScript(opts)
178
+ const kind = googleTagKind(opts.id)
179
+ if (kind == null) {
180
+ return inlineSafe(bootstrap)
181
+ }
182
+ const layer = layerOf(opts)
183
+ const loader = kind === 'gtm' ? gtmContainerScript(layer, opts.id) : gtagScript(layer, opts.id)
184
+
185
+ return inlineSafe(`${bootstrap};${redactionScript(layer)};${loader}`)
186
+ }
187
+
188
+ /**
189
+ * The hosts a page running a Google tag has to allow in `script-src`, `connect-src` and
190
+ * `img-src`, for Google Analytics 4, Tag Manager and Google Ads together.
191
+ *
192
+ * Taken from Google's CSP guide (developers.google.com/tag-platform/security/guides/csp) and
193
+ * folded into one list, because the platform adds one list to all three directives:
194
+ *
195
+ * - `*.googletagmanager.com` — gtm.js and gtag/js (`www.`), and their measurement pings;
196
+ * - `*.google-analytics.com` — GA4 collection (`region1.`, `www.`);
197
+ * - `*.g.doubleclick.net` — GA4 with Google signals and Ads (`stats.g.`, `googleads.g.`);
198
+ * - `ad.doubleclick.net` — Ads and Floodlight conversions;
199
+ * - `www.googleadservices.com` — the Ads conversion script;
200
+ * - `pagead2.googlesyndication.com` — Ads and GA4-with-ads pings;
201
+ * - `*.google.com` — `www.google.com` (the Ads script, consent-mode pings), `adservice.`, and the
202
+ * `analytics.google.com` collection endpoints.
203
+ *
204
+ * Every entry is an `https://` scheme, an optional `*.` label and a dotted host — the only shape
205
+ * the publisher's CSP filter lets through — and there are few enough to stay inside its per-slot
206
+ * cap. Google's country domains (`google.<TLD>`) cannot be named in that shape and are left out:
207
+ * what is lost is a remarketing ping from visitors on those domains, never the tag itself.
208
+ */
209
+ export const GOOGLE_TAG_CSP_SOURCES: readonly string[] = Object.freeze([
210
+ 'https://*.googletagmanager.com',
211
+ 'https://*.google-analytics.com',
212
+ 'https://*.g.doubleclick.net',
213
+ 'https://ad.doubleclick.net',
214
+ 'https://www.googleadservices.com',
215
+ 'https://pagead2.googlesyndication.com',
216
+ 'https://*.google.com',
217
+ ])
218
+
219
+ /**
220
+ * The hosts a Google tag frames: Tag Manager's service-worker and preview frames, and the Ads
221
+ * remarketing frame. For `frame-src`, which otherwise stays `'none'`.
222
+ */
223
+ export const GOOGLE_TAG_FRAME_SOURCES: readonly string[] = Object.freeze([
224
+ 'https://www.googletagmanager.com',
225
+ 'https://td.doubleclick.net',
226
+ ])
227
+
228
+ const GOOGLE = 'Google LLC'
229
+ const GOOGLE_PRIVACY = 'https://policies.google.com/privacy'
230
+
231
+ const analyticsService = (name: string, purpose: string, cookies: string[]): ConsentService => ({
232
+ name, provider: GOOGLE, category: CONSENT_ANALYTICS, purpose, cookies, privacyHref: GOOGLE_PRIVACY,
233
+ })
234
+
235
+ const adsService = (name: string, purpose: string, cookies: string[]): ConsentService => ({
236
+ name, provider: GOOGLE, category: CONSENT_MARKETING, purpose, cookies, privacyHref: GOOGLE_PRIVACY,
237
+ })
238
+
239
+ const UNTIL_ANALYTICS = 'Until analytics cookies are accepted it sets no cookies and sends only '
240
+ + 'cookieless measurement signals.'
241
+ const UNTIL_MARKETING = 'Until marketing cookies are accepted it sets no cookies and ad click '
242
+ + 'identifiers are redacted.'
243
+
244
+ /**
245
+ * What a Google tag discloses on the cookie policy, for `CookiePolicy`'s `services`.
246
+ *
247
+ * Read off the id's prefix, because that is all the page knows: `G-` is Google Analytics 4
248
+ * (`_ga`, and `_ga_<id without G->` which carries the session), `AW-` Google Ads, `DC-` Floodlight.
249
+ * A `GTM-` container and a `GT-` Google tag route to whatever their owner configured at Google,
250
+ * so both are disclosed as an analytics AND an advertising entry, worded as configured there —
251
+ * the policy may not claim less than the tag can do. An invalid id discloses nothing, matching
252
+ * {@link googleTagHeadScript}, which loads nothing for it.
253
+ */
254
+ export const googleTagServices = (id: string): ConsentService[] => {
255
+ if (!isGoogleTagId(id)) {
256
+ return []
257
+ }
258
+ const prefix = id.slice(0, id.indexOf('-'))
259
+ switch (prefix) {
260
+ case 'G':
261
+ return [analyticsService(
262
+ 'Google Analytics',
263
+ 'Measures how visitors use the site — pages viewed, time spent, device and approximate '
264
+ + `location — so it can be improved. ${UNTIL_ANALYTICS}`,
265
+ ['_ga', `_ga_${id.slice(2)}`],
266
+ )]
267
+ case 'AW':
268
+ return [adsService(
269
+ 'Google Ads',
270
+ 'Measures which ads led to a visit or a sign-up, and may add visitors to audiences for '
271
+ + `showing them ads elsewhere. ${UNTIL_MARKETING}`,
272
+ ['_gcl_au', '_gcl_aw'],
273
+ )]
274
+ case 'DC':
275
+ return [adsService(
276
+ 'Google Campaign Manager 360 (Floodlight)',
277
+ `Measures which ad campaigns led to a visit or a sign-up. ${UNTIL_MARKETING}`,
278
+ ['_gcl_au', '_gcl_dc'],
279
+ )]
280
+ default: {
281
+ const source = prefix === 'GTM' ? 'Google Tag Manager' : 'Google tag'
282
+ const where = prefix === 'GTM' ? 'in its container' : 'for it at Google'
283
+
284
+ return [
285
+ analyticsService(
286
+ `${source} — analytics`,
287
+ `Runs the analytics tags configured ${where}, typically Google Analytics. `
288
+ + UNTIL_ANALYTICS,
289
+ ['_ga', '_ga_*'],
290
+ ),
291
+ adsService(
292
+ `${source} — advertising`,
293
+ `Runs the advertising tags configured ${where}, typically Google Ads conversion `
294
+ + `tracking and remarketing. ${UNTIL_MARKETING}`,
295
+ ['_gcl_au', '_gcl_aw'],
296
+ ),
297
+ ]
298
+ }
299
+ }
300
+ }
@@ -0,0 +1,335 @@
1
+ import { describe, expect, test } from 'bun:test'
2
+ import {
3
+ CONSENT_KEY, DEFAULT_CONSENT_CATEGORIES, consentBootstrapScript,
4
+ } from '@owlmeans/consent'
5
+ import type { ConsentCategory } from '@owlmeans/consent'
6
+ import {
7
+ GOOGLE_TAG_CSP_SOURCES, GOOGLE_TAG_FRAME_SOURCES, googleTagHeadScript, googleTagKind,
8
+ googleTagServices, isGoogleTagId,
9
+ } from '../src/index.js'
10
+
11
+ /**
12
+ * The publisher's filter for slot-supplied CSP sources (`CSP_SOURCE_SHAPE` in viable's
13
+ * `sources/publisher/src/helpers/serve.ts`), copied because that is the gate these constants have
14
+ * to pass: an entry it rejects is silently dropped from the header, and the tag it was for is
15
+ * blocked with nothing in the page saying why.
16
+ */
17
+ const CSP_SOURCE_SHAPE =
18
+ /^(?:https:\/\/|wss:\/\/)?(?:\*\.)?[A-Za-z0-9][A-Za-z0-9-]*(?:\.[A-Za-z0-9][A-Za-z0-9-]*)+(?::[0-9]{1,5})?(?:\/[A-Za-z0-9._~%+&=@:/-]*)?$/
19
+
20
+ interface Element { id?: string, src?: string, async?: boolean }
21
+
22
+ /**
23
+ * Run an emitted snippet the way a browser runs an inline head script, against a window and a
24
+ * document that record what it did. The snippet is executed rather than pattern-matched because
25
+ * what matters is the ORDER in which things reach the queue, and the text only suggests it.
26
+ */
27
+ const browser = (stored?: { key?: string, record: Record<string, unknown> }) => {
28
+ const storage = new Map<string, string>()
29
+ if (stored != null) {
30
+ storage.set(stored.key ?? CONSENT_KEY, JSON.stringify(stored.record))
31
+ }
32
+ const loaded: Element[] = []
33
+ const byId = new Map<string, Element>()
34
+ const attach = (element: Element) => {
35
+ loaded.push(element)
36
+ if (element.id != null) byId.set(element.id, element)
37
+ }
38
+ const win: Record<string, unknown> = {
39
+ localStorage: { getItem: (key: string) => storage.get(key) ?? null },
40
+ }
41
+ const doc = {
42
+ cookie: '',
43
+ createElement: (): Element => ({}),
44
+ getElementById: (id: string) => byId.get(id) ?? null,
45
+ getElementsByTagName: () => [{ parentNode: { insertBefore: attach } }],
46
+ head: { appendChild: attach },
47
+ }
48
+
49
+ return {
50
+ win,
51
+ loaded,
52
+ run: (script: string) => {
53
+ // eslint-disable-next-line no-new-func
54
+ new Function('window', 'document', script)(win, doc)
55
+ },
56
+ /** The queue as `command:arg` strings; gtm.js's own object entry shows as `event:gtm.js`. */
57
+ queue: (name = 'dataLayer'): string[] =>
58
+ ((win[name] as unknown[] | undefined) ?? []).map(entry => {
59
+ const item = entry as { length?: number, event?: string }
60
+ if (typeof item.length === 'number') {
61
+ const args = Array.from(entry as ArrayLike<unknown>)
62
+
63
+ return args.slice(0, 2).map(arg => typeof arg === 'object' ? 'obj' : String(arg)).join(':')
64
+ }
65
+
66
+ return `event:${String(item.event)}`
67
+ }),
68
+ }
69
+ }
70
+
71
+ describe('isGoogleTagId / googleTagKind', () => {
72
+ const cases: [string, 'gtm' | 'gtag' | null][] = [
73
+ ['GTM-ABC1234', 'gtm'],
74
+ ['GTM-ABCD', 'gtm'],
75
+ ['GTM-ABCDEFGHIJKL', 'gtm'],
76
+ ['G-ABCDEF1234', 'gtag'],
77
+ ['GT-ABCD1234', 'gtag'],
78
+ ['AW-123456789', 'gtag'],
79
+ ['DC-1234567', 'gtag'],
80
+ ['G-ABCDEFGHIJKLMNOP', 'gtag'],
81
+ // Everything below must load nothing.
82
+ ['', null],
83
+ ['gtm-abc1234', null],
84
+ ['g-abcdef1234', null],
85
+ ['GTM-ABC', null],
86
+ ['GTM-ABCDEFGHIJKLM', null],
87
+ ['G-ABCDEFGHIJKLMNOPQ', null],
88
+ ['G-', null],
89
+ ['UA-12345678-1', null],
90
+ ['G-ABCD 1234', null],
91
+ [' G-ABCD1234', null],
92
+ ['G-ABCD1234\n', null],
93
+ ['G-ABCD1234"+alert(1)+"', null],
94
+ ['G-ABCD</script>', null],
95
+ ['GTM-ABCD1234&l=x', null],
96
+ ]
97
+
98
+ for (const [id, kind] of cases) {
99
+ test(`${JSON.stringify(id)} → ${String(kind)}`, () => {
100
+ expect(isGoogleTagId(id)).toBe(kind != null)
101
+ expect(googleTagKind(id)).toBe(kind)
102
+ })
103
+ }
104
+
105
+ test('a value that is not a string is not an id', () => {
106
+ expect(isGoogleTagId(undefined as never)).toBe(false)
107
+ expect(googleTagKind(null as never)).toBeNull()
108
+ })
109
+ })
110
+
111
+ describe('googleTagHeadScript — the order', () => {
112
+ test('gtag.js: consent default, then redaction, then js/config, then the library', () => {
113
+ const script = googleTagHeadScript({ id: 'G-ABCD1234' })
114
+ const page = browser()
115
+ page.run(script)
116
+
117
+ // What the tag obeys is what is on the queue when it loads, so the default has to be FIRST —
118
+ // not merely present.
119
+ expect(page.queue()).toEqual([
120
+ 'consent:default',
121
+ 'set:ads_data_redaction',
122
+ 'set:url_passthrough',
123
+ 'js:obj',
124
+ 'config:G-ABCD1234',
125
+ ])
126
+ expect(page.loaded.map(element => element.src)).toEqual([
127
+ 'https://www.googletagmanager.com/gtag/js?id=G-ABCD1234',
128
+ ])
129
+ expect(page.loaded[0].async).toBe(true)
130
+ // And in the text too: the library is requested after the default is declared.
131
+ expect(script.indexOf("'consent','default'")).toBeLessThan(script.indexOf('gtag/js'))
132
+ })
133
+
134
+ test('the redaction flags carry the right values', () => {
135
+ const page = browser()
136
+ page.run(googleTagHeadScript({ id: 'AW-123456789' }))
137
+ const sets = ((page.win.dataLayer as ArrayLike<unknown>[]) ?? [])
138
+ .map(entry => Array.from(entry))
139
+ .filter(args => args[0] === 'set')
140
+
141
+ expect(sets).toEqual([['set', 'ads_data_redaction', true], ['set', 'url_passthrough', false]])
142
+ })
143
+
144
+ test('Tag Manager: consent default, then redaction, then the container', () => {
145
+ const script = googleTagHeadScript({ id: 'GTM-ABC1234' })
146
+ const page = browser()
147
+ page.run(script)
148
+
149
+ expect(page.queue()).toEqual([
150
+ 'consent:default',
151
+ 'set:ads_data_redaction',
152
+ 'set:url_passthrough',
153
+ 'event:gtm.js',
154
+ ])
155
+ expect(page.loaded.map(element => element.src)).toEqual([
156
+ 'https://www.googletagmanager.com/gtm.js?id=GTM-ABC1234',
157
+ ])
158
+ expect(script.indexOf("'consent','default'")).toBeLessThan(script.indexOf('gtm.js'))
159
+ })
160
+
161
+ test('a returning visitor\'s decision is applied before the tag is configured', () => {
162
+ const page = browser({ record: { essential: true, analytics: true, marketing: false, v: 2 } })
163
+ page.run(googleTagHeadScript({ id: 'G-ABCD1234' }))
164
+ const queue = page.queue()
165
+
166
+ expect(queue.slice(0, 2)).toEqual(['consent:default', 'consent:update'])
167
+ expect(queue.indexOf('consent:update')).toBeLessThan(queue.indexOf('config:G-ABCD1234'))
168
+ expect(page.win.owlConsentAnalytics).toBe(true)
169
+ expect(page.win.owlConsentMarketing).toBe(false)
170
+ })
171
+
172
+ test('running it twice configures the tag once', () => {
173
+ // Two stampings or a hot reload must not double-count every page view.
174
+ const page = browser()
175
+ const script = googleTagHeadScript({ id: 'G-ABCD1234' })
176
+ page.run(script)
177
+ page.run(script)
178
+
179
+ expect(page.queue().filter(entry => entry.startsWith('config:'))).toHaveLength(1)
180
+ expect(page.queue().filter(entry => entry === 'consent:default')).toHaveLength(1)
181
+ expect(page.loaded).toHaveLength(1)
182
+ })
183
+
184
+ test('window.gtag is published for application events, and never replaced', () => {
185
+ const page = browser()
186
+ page.run(googleTagHeadScript({ id: 'G-ABCD1234' }))
187
+ expect(typeof page.win.gtag).toBe('function')
188
+
189
+ const owned = () => undefined
190
+ const other = browser()
191
+ other.win.gtag = owned
192
+ other.run(googleTagHeadScript({ id: 'G-ABCD1234' }))
193
+ expect(other.win.gtag).toBe(owned)
194
+ })
195
+
196
+ test('a custom queue is used by the tag and passed to the library', () => {
197
+ const page = browser()
198
+ page.run(googleTagHeadScript({ id: 'G-ABCD1234', dataLayerName: 'owlLayer' }))
199
+
200
+ expect(page.queue('owlLayer')).toContain('config:G-ABCD1234')
201
+ expect(page.loaded[0].src).toBe('https://www.googletagmanager.com/gtag/js?id=G-ABCD1234&l=owlLayer')
202
+ })
203
+
204
+ test('a queue name that is not an identifier falls back to dataLayer', () => {
205
+ const page = browser()
206
+ page.run(googleTagHeadScript({ id: 'G-ABCD1234', dataLayerName: 'a-b' }))
207
+
208
+ expect(page.queue()).toContain('config:G-ABCD1234')
209
+ expect(page.loaded[0].src).toBe('https://www.googletagmanager.com/gtag/js?id=G-ABCD1234')
210
+ })
211
+ })
212
+
213
+ describe('googleTagHeadScript — an invalid id', () => {
214
+ test('yields the consent bootstrap alone', () => {
215
+ // A mistyped tag must never cost the page its consent defaults.
216
+ for (const id of ['', 'UA-1234-1', 'G-x"+alert(1)']) {
217
+ const script = googleTagHeadScript({ id })
218
+
219
+ expect(script).toBe(consentBootstrapScript({ id } as never))
220
+ expect(script).not.toContain('googletagmanager')
221
+ expect(script).not.toContain('ads_data_redaction')
222
+ }
223
+ })
224
+ })
225
+
226
+ describe('googleTagHeadScript — safe inline in HTML', () => {
227
+ const hostile: ConsentCategory[] = [
228
+ ...DEFAULT_CONSENT_CATEGORIES,
229
+ {
230
+ key: 'x</script><!--y', labelKey: 'x', descriptionKey: 'x',
231
+ globalVar: 'probe', signals: ['personalization_storage'],
232
+ },
233
+ ]
234
+
235
+ test('no configured value can close the script element or open a comment', () => {
236
+ const script = googleTagHeadScript({
237
+ id: 'G-ABCD1234', categories: hostile, storageKey: 'k</SCRIPT>',
238
+ dataLayerName: '</script><script>alert(1)</script>',
239
+ })
240
+
241
+ expect(script.toLowerCase()).not.toContain('</script')
242
+ expect(script).not.toContain('<!--')
243
+ })
244
+
245
+ test('the escaped script still means what it said', () => {
246
+ // The backslashes are for the HTML parser; JavaScript must read the same values as before.
247
+ const key = 'k</script>'
248
+ const page = browser({ key, record: { 'x</script><!--y': true, v: 2 } })
249
+ page.run(googleTagHeadScript({ id: 'G-ABCD1234', categories: hostile, storageKey: key }))
250
+
251
+ expect(page.win.probe).toBe(true)
252
+ expect(page.queue()).toContain('consent:update')
253
+ expect(page.queue()).toContain('config:G-ABCD1234')
254
+ })
255
+ })
256
+
257
+ describe('GOOGLE_TAG_CSP_SOURCES / GOOGLE_TAG_FRAME_SOURCES', () => {
258
+ test('every entry passes the publisher\'s source filter, within its cap', () => {
259
+ for (const source of [...GOOGLE_TAG_CSP_SOURCES, ...GOOGLE_TAG_FRAME_SOURCES]) {
260
+ expect({ source, ok: CSP_SOURCE_SHAPE.test(source) }).toEqual({ source, ok: true })
261
+ expect(source.startsWith('https://')).toBe(true)
262
+ }
263
+ expect(GOOGLE_TAG_CSP_SOURCES.length).toBeLessThanOrEqual(10)
264
+ expect(new Set(GOOGLE_TAG_CSP_SOURCES).size).toBe(GOOGLE_TAG_CSP_SOURCES.length)
265
+ })
266
+
267
+ test('they cover Tag Manager, GA4 and Google Ads', () => {
268
+ // A host a CSP wildcard covers (`https://*.x.com` admits `www.x.com`, not `x.com`) counts.
269
+ const covered = (host: string) => GOOGLE_TAG_CSP_SOURCES.some(source => {
270
+ const pattern = source.replace('https://', '')
271
+
272
+ return pattern.startsWith('*.') ? host.endsWith(pattern.slice(1)) : host === pattern
273
+ })
274
+ for (const host of [
275
+ 'www.googletagmanager.com', 'region1.google-analytics.com', 'region1.analytics.google.com',
276
+ 'stats.g.doubleclick.net', 'googleads.g.doubleclick.net', 'ad.doubleclick.net',
277
+ 'www.googleadservices.com', 'pagead2.googlesyndication.com', 'www.google.com',
278
+ ]) {
279
+ expect({ host, covered: covered(host) }).toEqual({ host, covered: true })
280
+ }
281
+ expect(GOOGLE_TAG_FRAME_SOURCES).toEqual([
282
+ 'https://www.googletagmanager.com', 'https://td.doubleclick.net',
283
+ ])
284
+ })
285
+
286
+ test('they cannot be mutated by a consumer', () => {
287
+ expect(Object.isFrozen(GOOGLE_TAG_CSP_SOURCES)).toBe(true)
288
+ expect(Object.isFrozen(GOOGLE_TAG_FRAME_SOURCES)).toBe(true)
289
+ })
290
+ })
291
+
292
+ describe('googleTagServices', () => {
293
+ const categoryKeys = new Set(DEFAULT_CONSENT_CATEGORIES.map(category => category.key))
294
+
295
+ test('GA4 is analytics, with the session cookie named after the measurement id', () => {
296
+ const services = googleTagServices('G-ABCD1234')
297
+
298
+ expect(services).toHaveLength(1)
299
+ expect(services[0]).toMatchObject({ name: 'Google Analytics', category: 'analytics' })
300
+ expect(services[0].cookies).toEqual(['_ga', '_ga_ABCD1234'])
301
+ })
302
+
303
+ test('Google Ads and Floodlight are marketing', () => {
304
+ expect(googleTagServices('AW-123456789').map(service => service.category)).toEqual(['marketing'])
305
+ expect(googleTagServices('AW-123456789')[0].cookies).toContain('_gcl_au')
306
+ expect(googleTagServices('DC-1234567').map(service => service.category)).toEqual(['marketing'])
307
+ expect(googleTagServices('DC-1234567')[0].cookies).toContain('_gcl_dc')
308
+ })
309
+
310
+ test('a container or a Google tag discloses both, as configured there', () => {
311
+ // Whatever the owner put in the container can run, so the policy may not claim less.
312
+ for (const id of ['GTM-ABC1234', 'GT-ABCD1234']) {
313
+ const services = googleTagServices(id)
314
+
315
+ expect(services.map(service => service.category)).toEqual(['analytics', 'marketing'])
316
+ expect(services.every(service => /configured/.test(service.purpose ?? ''))).toBe(true)
317
+ }
318
+ })
319
+
320
+ test('every entry is complete and lands in a default category', () => {
321
+ for (const id of ['G-ABCD1234', 'GT-ABCD1234', 'AW-123456789', 'DC-1234567', 'GTM-ABC1234']) {
322
+ for (const service of googleTagServices(id)) {
323
+ expect(service.provider).toBe('Google LLC')
324
+ expect(service.privacyHref).toStartWith('https://policies.google.com/')
325
+ expect(categoryKeys.has(service.category)).toBe(true)
326
+ expect(service.cookies?.length ?? 0).toBeGreaterThan(0)
327
+ }
328
+ }
329
+ })
330
+
331
+ test('an invalid id discloses nothing, as it loads nothing', () => {
332
+ expect(googleTagServices('')).toEqual([])
333
+ expect(googleTagServices('UA-1234-1')).toEqual([])
334
+ })
335
+ })