@c15t/scripts 2.2.0 → 3.0.0-alpha.0

package/docs/integrations/google-tag-manager.md

@@ -1,154 +1,306 @@
 ---
 title: Google Tag Manager
-description: Deploy and manage marketing tags centrally with automatic consent
-  state synchronization.
-icon: google-tag-manager
+description: Load GTM with c15t consent signals and verify the tags inside your container.
 group: integrations
 ---
-Google Tag Manager (GTM) is Google's tag management system that lets you deploy and manage marketing tags, analytics scripts, and conversion pixels without modifying your codebase. Instead of hardcoding multiple scripts, you configure them through GTM's web interface.
 
-c15t automatically injects the GTM script into your page and syncs consent state with GTM using Consent Mode v2. GTM manages its own internal consent state and only fires tags when appropriate consent is granted, which means it can safely load before consent is collected.
+## Register the container
 
-This prevents GTM-managed scripts from loading without proper consent while giving you centralized control over your marketing stack.
+| Package manager | Command                     |
+| :-------------- | :-------------------------- |
+| npm             | `npm install @c15t/scripts` |
+| pnpm            | `pnpm add @c15t/scripts`    |
+| yarn            | `yarn add @c15t/scripts`    |
+| bun             | `bun add @c15t/scripts`     |
 
-> ℹ️ **Info:**
-> Use GTM if your team manages many tags centrally in the GTM UI. Use gtag.js if you only need GA4/Google Ads directly in code. Don't run both for the same destination unless intentional, or you may duplicate events.
+```ts title="src/consent-scripts.ts"
+import { googleTagManager } from '@c15t/scripts/google-tag-manager';
 
-## Integrate with c15t
+export const scripts = [googleTagManager({ id: 'GTM-XXXXXXX' })];
+```
 
-Use your GTM container ID, which begins with `GTM-`.
+Replace the container ID and pass `scripts` to your existing provider options.
+Remove the previous GTM snippet and any duplicate framework integration. The
+helper sends a `consent-update` event after consent changes; `updateEventName`
+customizes that event name.
 
-**React**
+## Register the scripts
 
-```tsx
-import { type ReactNode } from 'react';
-import { ConsentManagerProvider } from '@c15t/react';
-import { googleTagManager } from '@c15t/scripts/google-tag-manager';
+Complete your [framework quickstart](https://c15t.com/docs/frameworks) first. Keep its Inth
+endpoint, policy, styles and consent UI. Remove the vendor's original script,
+SDK initializer or tag-manager entry so c15t owns loading once.
 
-const scripts = [googleTagManager({ id: 'GTM-XXXXXXX' })];
+The `scripts` export in `src/consent-scripts.ts` is a configuration, not an
+initializer. Add it to your existing consent owner using the registration point
+below. These are partial edits to that owner, not additional providers.
 
-export function ConsentProvider({ children }: { children: ReactNode }) {
-  return (
-    <ConsentManagerProvider
-      options={{
-        mode: 'hosted',
-        backendURL: 'https://your-instance.c15t.dev',
-        scripts,
-      }}
-    >
-      {children}
-    </ConsentManagerProvider>
-  );
-}
+**Next.js**
+
+Import the configuration into the client boundary from your router guide:
+
+```ts
+import { ConsentRoot } from 'c15t/next';
+import { scripts } from './consent-scripts';
 ```
 
-**Next.js**
+Keep the server-resolved `state` and shared `consentConfig` from your
+router guide. Its manifest, init and save URLs stay in effect. Add
+`scripts` as a top-level prop on the existing root:
 
 ```tsx
-'use client';
+<ConsentRoot state={state} config={consentConfig} scripts={scripts}>
+  {children}
+</ConsentRoot>
+```
 
-import { type ReactNode } from 'react';
-import { ConsentManagerProvider } from '@c15t/nextjs';
-import { googleTagManager } from '@c15t/scripts/google-tag-manager';
+For a Pages Router or static-export setup using `ConsentProvider`, add
+`scripts` to its existing `options` instead. Keep the router-specific setup
+from [Next.js script loading](../frameworks/next/script-loader.md).
 
-const scripts = [googleTagManager({ id: 'GTM-XXXXXXX' })];
+**TanStack Start**
 
-export function ConsentProvider({ children }: { children: ReactNode }) {
+In your existing root route component, import the scripts alongside
+`ConsentRoot`. Keep the server loader from the [TanStack Start quickstart](https://c15t.com/docs/frameworks/tanstack-start/quickstart).
+
+```tsx
+import { Outlet } from '@tanstack/react-router';
+import { ConsentRoot } from 'c15t/tanstack-start';
+import { scripts } from '../consent-scripts';
+
+function Root() {
+  const state = Route.useLoaderData();
   return (
-    <ConsentManagerProvider
-      options={{
-        mode: 'hosted',
-        backendURL: '/api/c15t',
-        scripts,
-      }}
-    >
-      {children}
-    </ConsentManagerProvider>
+    <ConsentRoot state={state} backendURL={backendURL} initRoute={false} scripts={scripts}>
+      <Outlet />
+      {/* Keep your consent banner, dialog and preferences link here. */}
+    </ConsentRoot>
   );
 }
 ```
 
-**JavaScript**
+This edits the existing route. `Route` and `backendURL` come from its setup;
+keep the document shell and head components if they are part of your root.
+`initRoute={false}` keeps the quickstart's direct-backend initialization.
+If your app mounts a consent server route, retain its existing `initRoute`
+instead. Do not return script callbacks from a server function or route loader.
+
+**React**
+
+Import the scripts into your existing provider component:
 
 ```ts
-import { getOrCreateConsentRuntime } from 'c15t';
-import { googleTagManager } from '@c15t/scripts/google-tag-manager';
+import { ConsentProvider } from 'c15t/react';
+import { scripts } from './consent-scripts';
+```
+
+Keep the existing options and add `scripts`:
+
+```tsx
+<ConsentProvider options={{ ...consentOptions, scripts }}>
+  {children}
+</ConsentProvider>
+```
+
+Here `consentOptions` is your existing configuration, including
+`mode: hosted({ url: backendURL })`. Keep the banner, dialog and preferences
+link inside the provider. See [React script loading](../frameworks/react/script-loader.md).
+
+**Nuxt**
 
-getOrCreateConsentRuntime({
-  mode: 'hosted',
-  backendURL: 'https://your-instance.c15t.dev',
-  scripts: [googleTagManager({ id: 'GTM-XXXXXXX' })],
+Attach one loader from the root `app.vue`, after the Nuxt module has
+started its browser runtime. This keeps vendor callbacks in application code rather
+than serialized `nuxt.config.ts` runtime configuration.
+
+```vue title="app/app.vue"
+<script setup lang="ts">
+import { onUnmounted } from 'vue';
+import { createScriptLoader } from 'c15t/modules/script-loader';
+import { scripts } from '../src/consent-scripts';
+
+const nuxtApp = useNuxtApp();
+const kernel = useConsentKernel();
+let loader: ReturnType<typeof createScriptLoader> | undefined;
+
+const removeMountedHook = nuxtApp.hook('app:mounted', () => {
+  loader = createScriptLoader({ kernel, scripts });
+});
+onUnmounted(() => {
+  removeMountedHook();
+  loader?.dispose();
 });
+</script>
+
+<template>
+  <ConsentRoot />
+  <NuxtPage />
+</template>
 ```
 
-## How c15t loads it
+Merge the setup code into your root and retain its footer and preferences
+link. `useConsentKernel` is auto-imported by the c15t Nuxt module. Adjust the
+relative script import if your `app.vue` is at the project root. This loader
+waits until the module has applied browser persistence and privacy signals,
+then reads the current snapshot and observes future changes. Do not also register these scripts
+in another loader. See the [Nuxt quickstart](https://c15t.com/docs/frameworks/nuxt/quickstart).
 
-* **Category:** `necessary` (Tag Managers)
-* **Loads when:** [`alwaysLoad`](/docs/frameworks/react/script-loader#always-load) — runs on page start with Consent Mode v2 defaults set to denied
-* **On consent change:** c15t pushes a Consent Mode v2 `update` to the data layer; GTM-managed tags re-evaluate against the new state
+**Vue**
 
-## Configure the integration
+Use the kernel already provided by the Vue plugin. Merge this setup into
+`App.vue`, whose lifetime covers the application:
 
-1. **Creating a Tag Manager Container**
+```vue title="src/App.vue"
+<script setup lang="ts">
+import { onMounted, onUnmounted } from 'vue';
+import { createScriptLoader } from 'c15t/modules/script-loader';
+import { useConsentKernel } from 'c15t/vue/vue-plugin';
+import ConsentRoot from 'c15t/vue/consent-root';
+import { scripts } from './consent-scripts';
 
-   > 📝 Note:
-   > This step is optional if you already have a Tag Manager container. Ensure your container has consent overview enabled.
+const kernel = useConsentKernel();
+let loader: ReturnType<typeof createScriptLoader> | undefined;
 
-   After signing into Google Tag Manager, you can create a new container.
-   Continue to Google Tag Manager
+onMounted(() => {
+  loader = createScriptLoader({ kernel, scripts });
+});
+onUnmounted(() => loader?.dispose());
+</script>
 
-   1. In Tag Manager, click Admin > Container Settings.
-   2. Under Additional Settings, select "Enable consent overview".
+<template>
+  <ConsentRoot />
+  <main>Your application</main>
+</template>
+```
 
-   Enable consent overview
+Keep your existing page content and preferences link. The plugin still owns
+the kernel and persistence; this component owns only the vendor loader.
+Do not register the same scripts in plugin configuration as well. See the
+[Vue quickstart](https://c15t.com/docs/frameworks/vue/quickstart).
 
-2. **Custom Update Trigger** We now need to create a custom trigger in GTM to trigger the update event, this is the trigger that is fired when the consent state is updated, e.g. user gives consent to a specific purpose.
+**Astro**
 
-   In GTM, you can create a new trigger by clicking on the "Triggers" tab and then clicking on "New".
+Point the existing Astro integration at a client module. Keep its `mode`,
+`ui` and framework integration from the [Astro quickstart](https://c15t.com/docs/frameworks/astro/quickstart).
+Import `fileURLToPath` in your Astro configuration:
 
-   For the event name, you can use the default "consent-update", this is customizable later so you can change it if you want.
+```js title="astro.config.mjs"
+import { fileURLToPath } from 'node:url';
+```
 
-   Create trigger
+Add this option to the existing `c15t({ ... })` call. Resolve the path from
+the configuration file because Astro injects the import into a virtual module:
 
-3. **Update tags** Now for your existing tags, you can add the "consent-update" trigger to the tag, this will fire the update event when the consent state is updated & it has the appropriate consent state.
+```js
+clientEntrypoint: fileURLToPath(new URL('./src/c15t.client.ts', import.meta.url)),
+```
+
+Export the scripts from that module:
 
-   Update tags
+```ts title="src/c15t.client.ts"
+import type { C15tClientOptionsExtension } from '@c15t/astro';
+import { scripts } from './consent-scripts';
 
-## Tracking events in your app
+export default { scripts } satisfies C15tClientOptionsExtension;
+```
 
-GTM is `alwaysLoad: true`, so the GTM container and `window.dataLayer` are present from page start regardless of consent. Calls like `dataLayer.push({ event: 'signup' })` are **safe at any time** — Consent Mode v2 defaults are set to denied before the user makes a choice, and GTM-managed tags only fire when the matching consent has been granted.
+The integration passes this extension to its shared browser runtime. Vendor
+helpers contain callbacks, so do not put them in the serialized `scripts`
+option in `astro.config.mjs`. Keep one runtime across consent islands and
+`ClientRouter` navigation.
 
-```ts
-window.dataLayer = window.dataLayer || [];
-window.dataLayer.push({ event: 'signup' });
+**Svelte**
+
+Import the scripts in the component that owns your existing provider and
+pass them as a top-level prop:
+
+```svelte title="src/App.svelte"
+<script lang="ts">
+  import { ConsentManagerProvider, hosted } from '@c15t/svelte';
+  import { scripts } from './consent-scripts';
+
+  const backendURL = import.meta.env.VITE_C15T_BACKEND_URL;
+  if (!backendURL) throw new Error('Set VITE_C15T_BACKEND_URL');
+  const mode = hosted({ url: backendURL });
+</script>
+
+<ConsentManagerProvider {mode} {scripts}>
+  <!-- Keep your application, consent UI and preferences link here. -->
+</ConsentManagerProvider>
+```
+
+Retain the styles and consent UI from the [Svelte quickstart](https://c15t.com/docs/frameworks/svelte/quickstart).
+The provider owns the loader and disposes it on unmount.
+
+**SvelteKit**
+
+Add the scripts to the existing root layout provider. Keep the server load
+and its serializable prefetch data from the [SvelteKit quickstart](https://c15t.com/docs/frameworks/sveltekit/quickstart).
+
+```svelte title="src/routes/+layout.svelte"
+<script lang="ts">
+  import { ConsentManagerProvider, hosted } from '@c15t/svelte';
+  import { scripts } from '../consent-scripts';
+
+  let { children, data } = $props();
+  const mode = hosted({ url: data.backendURL });
+</script>
+
+<ConsentManagerProvider {mode} {scripts} prefetch={data.prefetch}>
+  {@render children()}
+  <!-- Keep your consent UI and preferences link here. -->
+</ConsentManagerProvider>
 ```
 
-You do not need to wrap `dataLayer.push(...)` in a `useConsentManager().has(...)` check — the consent gate happens inside GTM, not inside c15t.
+Import vendor helpers in the layout component, not in `+layout.server.ts`.
+For static hosting, keep your browser-only `mode` setup and omit request
+prefetch; the `scripts` prop stays the same. If you pass an externally owned
+`runtime` to the provider, register scripts when creating that runtime instead.
+
+**JavaScript**
+
+Attach the loader to your existing kernel before calling
+`kernel.commands.init()`:
+
+```ts
+import { createScriptLoader } from 'c15t/modules/script-loader';
+import { scripts } from './consent-scripts';
+
+const loader = createScriptLoader({ kernel, scripts });
+```
 
-## Verify setup
+Call `loader.dispose()` when that application instance is destroyed.
+`kernel` is the hosted kernel from your quickstart. A provider-owned kernel
+already has a loader; do not attach a second one. See
+[JavaScript script loading](../frameworks/javascript/script-loader.md).
 
-1. Open GTM Preview mode and confirm your container (`GTM-...`) loads on page load.
-2. Before giving consent, confirm non-essential tags do not fire in GTM Preview.
-3. Accept consent in the c15t banner/dialog and confirm a `consent-update` event appears in the GTM event timeline.
-4. Confirm measurement/marketing tags fire only after the matching consent is granted.
-5. Revoke consent and confirm a new `consent-update` event appears and affected tags stop firing.
+## Consent Mode is not a zero-request gate
 
-## Types
+This helper sets `alwaysLoad: true`. It prepares the Google queue, sends consent
+defaults and updates, and loads Google's script even before a visitor makes a
+choice. That is different from preventing any request to Google until consent.
+Google describes the distinction in its
+[Consent Mode overview](https://developers.google.com/tag-platform/security/concepts/consent-mode).
 
-### GoogleTagManagerOptions
+The default mapping is:
 
-|Property|Value|
-|:--|:--|
-|Type Name|\`GoogleTagManagerOptions\`|
-|Source Path|\`./packages/scripts/src/vendors/tag-managers/google-tag-manager.ts\`|
+| c15t category   | Google consent types                               |
+| --------------- | -------------------------------------------------- |
+| `necessary`     | `security_storage`                                 |
+| `functionality` | `functionality_storage`                            |
+| `measurement`   | `analytics_storage`                                |
+| `marketing`     | `ad_storage`, `ad_user_data`, `ad_personalization` |
+| `experience`    | `personalization_storage`                          |
 
-\*ExtractedTypeTable: Could not extract "GoogleTagManagerOptions" from "./packages/scripts/src/vendors/tag-managers/google-tag-manager.ts" using base path "/home/runner/work/c15t/c15t". Verify the path/name and that the file is included by your tsconfig.\*
+`consentMapping` replaces the mapping when supplied. Keep the full set of
+signals your integration needs. Test both default and update commands and the
+actual tag behavior. Do not infer a saved grant from an allowed default under an
+opt-out policy.
 
-### Script
+## Configure the container too
 
-|Property|Value|
-|:--|:--|
-|Type Name|\`Script\`|
-|Source Path|\`./packages/core/src/libs/script-loader/types.ts\`|
+Loading GTM with consent signals does not make every custom tag consent-aware.
+Configure the appropriate consent checks and triggers for tags inside the
+container. Inspect their requests after rejection and revocation, including
+non-Google tags. Use Google Tag Assistant alongside the browser Network panel.
 
-\*ExtractedTypeTable: Could not extract "Script" from "./packages/core/src/libs/script-loader/types.ts" using base path "/home/runner/work/c15t/c15t". Verify the path/name and that the file is included by your tsconfig.\*
+If the requirement is no Google request before permission, do not deploy this
+always-loaded helper unchanged. Choose and verify an explicitly gated setup.