@c15t/scripts 3.0.0-alpha.2 → 3.0.0-alpha.4

package/docs/frameworks/javascript/scripts.md

@@ -0,0 +1,137 @@
+---
+title: Scripts
+description: Register vendor scripts with @c15t/browser, createConsentRuntime or
+  a consent kernel in JavaScript, and control what happens when a visitor
+  withdraws permission.
+group: frameworks
+---
+
+## Register scripts where you start c15t
+
+Pass the `scripts` list to whichever API starts c15t. The list is the same in
+each case, built from `@c15t/integrations` helpers or your own script objects:
+
+| Setup           | Where `scripts` goes                                                                                                                                                    |
+| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `@c15t/browser` | `init({ backendURL, scripts })`, as in the [quickstart](https://c15t.com/docs/frameworks/javascript/quickstart#start-c15t).                                             |
+| `c15t/runtime`  | `createConsentRuntime({ mode, scripts })`, as in [headless](https://c15t.com/docs/frameworks/javascript/headless#create-the-runtime).                                   |
+| Your own kernel | `createScriptLoader({ kernel, scripts })`. See [script loader](https://c15t.com/docs/frameworks/javascript/modules/script-loader#attach-the-loader-to-your-own-kernel). |
+
+The quickstart's `src/scripts.ts` shows PostHog and X Pixel:
+
+```ts title="src/scripts.ts"
+import { posthog } from '@c15t/integrations/posthog';
+import { xPixel } from '@c15t/integrations/x-pixel';
+
+export const scripts = [
+	posthog({
+		id: 'phc_your_project_key',
+		initOptions: { cookieless_mode: 'never' },
+		loadMode: 'after-consent',
+	}),
+	xPixel({ pixelId: 'your-pixel-id' }),
+];
+```
+
+Each [integration guide](../../integrations/overview.md) gives the helper and
+options for one vendor. For a vendor without a helper, write the object
+yourself:
+
+```ts
+const scripts = [
+	{
+		id: 'analytics',
+		src: 'https://analytics.example/sdk.js',
+		category: 'measurement',
+		onLoad: () => window.analytics?.track('page_view'),
+	},
+];
+```
+
+`window.analytics` stands for your vendor's global. The
+[script loader](https://c15t.com/docs/frameworks/javascript/modules/script-loader) page lists
+every field and callback.
+
+## When the script loader downloads
+
+With `@c15t/browser` from npm, the script loader and the network blocker
+share a separate chunk. It loads when c15t starts, and only if `scripts` is
+not empty or `networkBlocker` has rules, so a page with neither never
+downloads it. On a page with either, the browser requests it after your
+JavaScript has run, which delays a returning visitor's consented scripts and
+held requests by one request.
+
+Your bundler names that chunk, so c15t cannot link it from your HTML. To
+start the download earlier, add a `<link rel="modulepreload">` for the chunk
+your build emits for `@c15t/core/dist/modules/loader-and-blocker.js`. With
+Vite, `.vite/manifest.json` lists it under that path when `build.manifest` is
+on. Give the link `fetchpriority="low"`. c15t needs the chunk only when it
+starts, and at the default priority the preload can delay your app's own
+chunks over HTTP/1.1. The script-tag build, `c15t.js`, already contains the
+loader.
+
+## Gate a snippet in your HTML
+
+`@c15t/browser` also runs `<script type="text/plain" data-c15t-category>`
+tags in your `index.html` once their category is allowed, in page order. Use
+it for a vendor snippet you would rather keep in HTML. `createConsentRuntime`
+and a plain kernel do not scan the page for these tags;
+`activateGatedScripts(snapshot)` from `@c15t/browser` runs them for you.
+
+With the `nonce` option set, `@c15t/browser` runs only the tags that carry the
+same `nonce`, and marks the others `data-c15t-activated="untrusted"`. Pass
+`{ nonce }` as the third argument of `activateGatedScripts` for the same
+check. See [Content Security Policy](https://c15t.com/docs/frameworks/javascript/content-security-policy).
+
+## When a visitor withdraws permission
+
+A script that has run cannot be unloaded. `@c15t/browser` and
+`createConsentRuntime` reload the page after a visitor turns off a category
+they had allowed, so the new page starts without that vendor. Allowing a
+category never reloads.
+
+Set `reloadOnConsentRevoked: false` to handle withdrawal yourself, for
+example with the vendor's opt-out call in the script's `onConsentChange`.
+Until the next page load, code that already ran keeps running.
+`callbacks.onBeforeConsentRevocationReload` runs right before the reload, for
+work that must finish first. A kernel you create yourself does not reload;
+add `watchRevocationReload` from `c15t` if you want it.
+
+## Keep one owner per vendor
+
+Use stable script IDs and remove the vendor's original snippet, so each
+vendor loads once and only through c15t. Ordinary scripts wait for
+permission. Helpers with `alwaysLoad` load at once and pass consent to the
+vendor's own API instead. Read the individual integration guide before
+assuming all helpers have the same network behavior.
+
+Create `init()` or the runtime once per page. A second client, or a second
+loader on a kernel that `@c15t/browser` or `createConsentRuntime` owns, loads
+vendors twice.
+
+## Let visitors turn off one vendor
+
+A visitor can allow marketing and still switch off one vendor in it. Declare
+the vendors in the `vendors` option and render the switch yourself; helpers
+from `@c15t/integrations` already carry their vendor slug. See
+[vendor consent](https://c15t.com/docs/frameworks/javascript/vendor-consent).
+
+## Clear stored tracking data
+
+Script gating does not remove cookies or Web Storage entries that a script
+already wrote. Configure [clear on revocation](https://c15t.com/docs/frameworks/javascript/clear-on-revocation)
+to delete them when their category is denied.
+
+## Send your own events to allowed vendors
+
+To send your own analytics events only to the vendors a visitor allows, use
+the event dispatcher from `@c15t/integrations`. See
+[send events only to allowed integrations](../../integrations/overview.md#send-events-only-to-allowed-integrations).
+
+## Check it works
+
+Run the app in a private window with the Network tab open.
+
+1. Filter for each vendor's host. Nothing loads before a choice.
+2. Allow one category. Only that category's vendors load.
+3. Withdraw it. The page reloads and the vendor stays absent.

package/docs/frameworks/next/embeds.md

@@ -0,0 +1,90 @@
+---
+title: Embeds
+description: Keep YouTube videos, maps and other iframes out of a Next.js page
+  until their consent category is allowed, with ConsentGate or the iframe
+  blocker in ConsentRoot.
+group: frameworks
+---
+
+## Pick a method
+
+| Method             | Use it when                                                                                              |
+| ------------------ | -------------------------------------------------------------------------------------------------------- |
+| `ConsentGate`      | You render the iframe in a React component and want a placeholder until the visitor allows its category. |
+| The iframe blocker | The iframe comes from markup you do not render with a component, such as CMS or Markdown content.        |
+
+Both keep the iframe's `src` out of the page until the category is allowed, so
+the embed's host receives no request before consent.
+
+## Gate an embed with ConsentGate
+
+Wrap the iframe in `ConsentGate` in a Client Component:
+
+```tsx title="components/video-embed.tsx"
+'use client';
+
+import { ConsentGate } from 'c15t/next';
+
+export const VideoEmbed = () => (
+	<ConsentGate category="measurement">
+		<iframe
+			className="video-frame"
+			sandbox="allow-scripts allow-same-origin allow-presentation"
+			src="https://www.youtube-nocookie.com/embed/czTksCF6X8Y"
+			title="YouTube video"
+			allow="accelerometer; autoplay; encrypted-media; gyroscope; picture-in-picture"
+			allowFullScreen
+		/>
+	</ConsentGate>
+);
+```
+
+Import `VideoEmbed` into any page or Server Component under the layout that
+mounts `ConsentRoot`; only this file needs `'use client'`. The iframe stays out
+of the page until the visitor allows measurement, and a placeholder with a
+button that opens the preference dialog takes its place.
+
+Pick the category that matches what the embed does. The example uses
+measurement for YouTube because its player measures views. A map or chat
+widget usually belongs under functionality or experience.
+
+What the server HTML contains depends on how your layout passes consent state.
+[ConsentGate](https://c15t.com/docs/frameworks/next/components/consent-gate) covers the
+default, awaited and Pages Router layouts, the placeholder and its props.
+
+## Gate an iframe with the iframe blocker
+
+`ConsentRoot` runs the iframe blocker in the browser by default. Give an
+iframe `data-src` instead of `src`, and a `data-category`:
+
+```html title="Markup from your CMS"
+<iframe
+  data-src="https://www.google.com/maps/embed?pb=YOUR_EMBED_ID"
+  data-category="functionality"
+  title="Store map"
+></iframe>
+```
+
+The server HTML has no `src`, so nothing loads before hydration. After
+hydration, c15t sets `src` from `data-src` when the category is allowed and
+removes `src` when the category is withdrawn. It watches the page, so iframes
+added by client-side navigation are handled too. Add `data-vendor` with a
+vendor ID to also block the iframe while the visitor has turned that vendor
+off.
+
+To turn the blocker off, pass `options={{ iframeBlocker: false }}` to
+`ConsentRoot`.
+
+## Verify the embeds
+
+Open the production build in a private window with DevTools open, under a
+policy that asks for consent.
+
+1. View the page source. No iframe has a `src` pointing at
+   `youtube-nocookie.com` or `google.com/maps`, and the Network panel shows no
+   request to them.
+2. Allow the embed's category and save. The iframe loads.
+3. Withdraw the category and save. The page reloads without the embed.
+
+The [YouTube](../../integrations/youtube.md) and
+[Google Maps](../../integrations/google-maps.md) guides cover sizing and titles.

package/docs/frameworks/next/network-blocker.md

@@ -0,0 +1,153 @@
+---
+title: Network blocker
+description: Hold fetch and XMLHttpRequest calls in a Next.js app until their
+  consent category is allowed, with networkBlocker rules on ConsentRoot.
+group: frameworks
+---
+
+## Add rules
+
+The network blocker stops `fetch` and `XMLHttpRequest` calls to domains you
+list until the visitor grants their category. Use it for beacons and API calls
+that bypass script loading, such as a pixel fired by an SDK already on the
+page. Load vendor SDKs through [`scripts`](./scripts.md)
+first, so they do not run at all before consent.
+
+Define the rules in `components/consent.tsx` and pass them to `ConsentRoot`.
+`onRequestBlocked` is a function, so the rules cannot come from a Server
+Component.
+
+```tsx title="components/consent.tsx (partial)"
+import type { ConsentRootProps } from 'c15t/next';
+
+const networkBlocker: NonNullable<ConsentRootProps['networkBlocker']> = {
+	rules: [
+		{
+			id: 'google-analytics',
+			domain: 'google-analytics.com',
+			category: 'measurement',
+		},
+		{
+			id: 'meta-pixel',
+			domain: 'facebook.com',
+			pathIncludes: '/tr',
+			category: 'marketing',
+		},
+	],
+};
+
+// On the existing root:
+<ConsentRoot
+	state={state}
+	config={consentConfig}
+	scripts={scripts}
+	networkBlocker={networkBlocker}
+>
+```
+
+Keep the page content inside `ConsentRoot`. Blocking starts when it renders, so
+components outside it that send requests while rendering, and modules evaluated
+before it, are not covered. Requests your server makes, in Server Components,
+route handlers or `getServerSideProps`, are not blocked either.
+
+## Match requests with rules
+
+Each rule names a `domain` and the consent `category` a request needs. The
+domain also matches its subdomains: `google-analytics.com` covers
+`www.google-analytics.com`. `pathIncludes` narrows the rule to paths that
+contain a substring, and `methods` narrows it to HTTP methods. A request is
+blocked when a matching rule's condition is not met by the visitor's
+effective permissions.
+
+`category` takes the same conditions as scripts:
+
+```ts
+{ category: 'measurement' }
+{ category: { and: ['measurement', 'marketing'] } }
+{ category: { or: ['measurement', 'marketing'] } }
+```
+
+Add `vendor` to also block the request while the visitor has turned that
+vendor off. IAB TCF rules use `vendorId` and the `iab*` purpose fields
+instead.
+
+| Option               | Default  | Purpose                                                      |
+| -------------------- | -------- | ------------------------------------------------------------ |
+| `rules`              | required | Rules described above                                        |
+| `enabled`            | `true`   | Set `false` to keep the rules but stop blocking              |
+| `logBlockedRequests` | `true`   | Log each blocked request with `console.warn`                 |
+| `onRequestBlocked`   | none     | Called with `{ method, url, rule }` for each blocked request |
+
+## What a blocked request looks like
+
+The blocker wraps `window.fetch` and `XMLHttpRequest`. A blocked `fetch`
+resolves to a `451` response with the status text
+`Request blocked by consent`, and nothing is sent. A blocked XHR is aborted
+and fires an `error` event. Requests that match no rule are not delayed.
+
+## When blocking starts
+
+The provider holds matching requests from its first render in the browser,
+before any of its children render or run effects. That covers requests from
+child components, including their mount effects, and from effects in
+components rendered next to the provider. The blocker module itself loads
+after mount and decides each held request. Apps without `networkBlocker` do
+not download it.
+
+The standalone `useNetworkBlocker` hook works the same way from the first
+render of the component that calls it. That render patches `fetch` and
+`XMLHttpRequest`. If React throws the render away and never commits it, the
+hold ends after 10 seconds. Nothing checked consent for the requests it held,
+so they fail the way the blocker fails a blocked request: a 451 response for
+`fetch`, a failed XHR. The same happens when the component unmounts before
+the blocker loads.
+
+While consent is unknown, a matching request that would be blocked waits
+instead of failing. Consent is unknown until the policy has loaded, which is
+also when a returning visitor's stored choice takes effect. The request is
+then sent if the choice allows it and blocked otherwise. If the policy fails
+to load, optional categories stay denied and waiting requests are blocked.
+If the policy request never finishes, they keep waiting and are never sent.
+
+A synchronous XHR cannot wait. Before the blocker module has loaded, a
+matching one throws a `NetworkError` from `send()`. After that, one that
+consent does not allow yet is blocked.
+
+## What the network blocker cannot stop
+
+The blocker only sees requests made after the provider starts rendering in
+the browser, through `fetch` or `XMLHttpRequest`. It cannot stop:
+
+* Code that runs before the provider renders: inline scripts in the HTML,
+  third-party tags in `<head>`, scripts loaded before hydration (such as
+  `next/script` with `beforeInteractive`), and client modules that evaluate
+  earlier. Webpack builds evaluate a route's client component modules when
+  its chunk loads, so their top-level code runs first. Turbopack evaluates a
+  client component module when its first element renders, which inside the
+  provider is after blocking starts.
+* Code that saved its own reference to `fetch` or `XMLHttpRequest` before the
+  provider rendered.
+* `navigator.sendBeacon`, `WebSocket`, `EventSource`, and requests made by
+  `<img>`, `<script>` or `<iframe>` elements, web workers and service
+  workers.
+* With the standalone `useNetworkBlocker` hook instead of the provider
+  option, requests sent before the component that calls it renders.
+  Blocking starts in that component's first render, not the provider's.
+
+Keep tracking calls out of that window:
+
+* Send them from an effect or an event handler, never at module top level.
+* Load vendor SDKs through `scripts` instead of a `<script>` tag or
+  `next/script`, so they wait for consent before they run at all.
+* Check `useConsent('measurement')` (or the category you need) before you
+  call a vendor from your own code, and treat the blocker as a backstop.
+
+## Verify the blocked requests
+
+Open the production build in a private window with the DevTools Network panel
+open, under a policy that asks for consent.
+
+1. Before a choice, requests matching a rule are absent from the Network panel,
+   and the console logs each blocked request.
+2. Allow the rule's category and save. Matching requests go out.
+3. Reject, reload, and check that they stay absent.

package/docs/frameworks/next/scripts.md

@@ -0,0 +1,196 @@
+---
+title: Scripts
+description: Register vendor scripts in a Next.js ConsentRoot, check how each
+  vendor loads, let visitors turn off one vendor and clear stored data after
+  revocation.
+group: frameworks
+---
+
+## Install the script helpers
+
+The [App Router](https://c15t.com/docs/frameworks/next/app-router),
+[Pages Router](https://c15t.com/docs/frameworks/next/pages-router) and
+[static export](https://c15t.com/docs/frameworks/next/static-export) guides already register
+scripts. Use this page to add vendors to an existing setup or to change how
+they load. Install the helpers if you have not:
+
+| Package manager | Command                                |
+| :-------------- | :------------------------------------- |
+| npm             | `npm install @c15t/integrations@alpha` |
+| pnpm            | `pnpm add @c15t/integrations@alpha`    |
+| yarn            | `yarn add @c15t/integrations@alpha`    |
+| bun             | `bun add @c15t/integrations@alpha`     |
+
+Keep `c15t.config.ts`, the manifest route and the layout from your router
+guide. Adding a vendor needs no server change. Server-rendered state, a
+streamed promise and browser initialization with `state={{}}` all reach the
+same `ConsentRoot`, and no script loads until the browser has a resolved
+policy and the visitor's choice allows it.
+
+## Register scripts in a client wrapper
+
+The [runnable Next.js example](https://c15t.com/docs/examples) uses PostHog for measurement and
+X Pixel for marketing. Replace the placeholder IDs `phc_your_project_key` and
+`your-pixel-id` with your own. Remove a vendor's entry to leave it out, or
+replace its helper with the [integration](../../integrations/overview.md) your
+application uses. Include the
+measurement and marketing categories in your policy for these two vendors.
+
+Create `lib/scripts.ts` with the example's script configuration:
+
+```ts title="lib/scripts.ts"
+import { posthog } from '@c15t/integrations/posthog';
+import { xPixel } from '@c15t/integrations/x-pixel';
+import type { Script } from 'c15t';
+
+export const scripts: Script[] = [
+	posthog({
+		id: 'phc_your_project_key',
+		initOptions: { cookieless_mode: 'never' },
+		loadMode: 'after-consent',
+	}),
+	xPixel({ pixelId: 'your-pixel-id' }),
+];
+```
+
+PostHog waits for measurement consent here. `cookieless_mode: 'never'` disables
+cookieless capture after rejection. X Pixel waits for marketing consent. Remove
+any existing loader for these vendors, including `next/script` and tag-manager
+entries, so each integration loads once.
+
+Create this client wrapper. It owns everything that has to run in the browser:
+the consent config, the scripts, the banner, the dialog and a persistent
+preferences link. The layout or `_app.tsx` passes only the visitor's state.
+
+```tsx title="components/consent.tsx"
+'use client';
+
+import {
+	ConsentBanner,
+	ConsentDialog,
+	ConsentDialogLink,
+	ConsentRoot,
+} from 'c15t/next';
+import type { ConsentRootProps } from 'c15t/next';
+import type { ReactNode } from 'react';
+
+import { consentConfig } from '@/c15t.config';
+import { scripts } from '@/lib/scripts';
+
+interface ConsentProps {
+	children: ReactNode;
+	state: ConsentRootProps['state'];
+}
+
+export const Consent = ({ children, state }: ConsentProps) => (
+	<ConsentRoot state={state} config={consentConfig} scripts={scripts}>
+		{children}
+		<ConsentBanner />
+		<ConsentDialog />
+		<footer>
+			<ConsentDialogLink>Privacy settings</ConsentDialogLink>
+		</footer>
+	</ConsentRoot>
+);
+```
+
+Import `consentConfig` in this `'use client'` file, as shown, and do not pass it
+from a Server Component. `defineConsentConfig` marks its result with a symbol
+key, and React cannot send an object with symbol keys from a Server Component
+to a Client Component.
+
+`ConsentRoot` already provides the consent runtime. Mount this wrapper once and
+do not add a second provider. Keep your site's content and footer inside it.
+
+The files import through the `@/` path alias that `create-next-app` sets up.
+With a `src/` directory the alias points at `src/`, so the same imports work.
+Without the alias, use relative paths.
+
+## Register several vendors
+
+Every helper goes in the same `scripts` array in `lib/scripts.ts`, in the App
+Router and the Pages Router alike. This array loads Google Tag Manager and
+Meta Pixel together:
+
+```ts title="lib/scripts.ts (partial)"
+import { googleTagManager } from '@c15t/integrations/google-tag-manager';
+import { metaPixel } from '@c15t/integrations/meta-pixel';
+import type { Script } from 'c15t';
+
+export const scripts: Script[] = [
+	googleTagManager({ id: 'GTM-XXXXXXX' }),
+	metaPixel({ pixelId: 'YOUR_PIXEL_ID' }),
+];
+```
+
+Each helper keeps its own consent rules. Meta Pixel waits for marketing, and
+Google Tag Manager follows the
+[Consent Mode contract](../../integrations/google-tag-manager.md). Remove the
+container and pixel snippets from `pages/_document.tsx` or your layout, so each
+vendor loads once. Both helpers throw on an empty ID, so leave a helper out of
+the array until you have its ID.
+
+## Check each vendor's loading behavior
+
+The example configures PostHog to load after consent and turns off cookieless
+capture. Its default helper can load before consent and use the SDK's own
+consent controls. Read the [PostHog guide](../../integrations/posthog.md) before
+you change those settings.
+
+Ordinary scripts wait for their category's permission. Give each script a
+stable, unique `id`, and remove any other loader for the same vendor. Helpers
+with `alwaysLoad` can load an SDK before permission is granted, so a category
+alone does not guarantee that no request happens. See the
+[vendor guides](../../integrations/overview.md) for each helper's contract.
+
+Removing a script element cannot undo JavaScript that already ran or requests
+already sent. When a visitor turns off a category they had granted,
+`ConsentRoot` reloads the page, so the next page runs only permitted code. See
+[reload after revocation](https://c15t.com/docs/frameworks/next/components/consent-root#reload-after-revocation).
+
+Use [custom integrations](../../integrations/building-integrations.md) for a
+vendor without a helper. Google helpers follow the
+[Consent Mode contract](../../integrations/google-tag-manager.md).
+
+## Embeds and other requests
+
+Scripts cover vendor code c15t loads for you. For the rest:
+
+* [Embeds](./embeds.md) keeps iframes out of the page with
+  `ConsentGate` or the iframe blocker.
+* [Network blocker](./network-blocker.md) holds `fetch` and
+  XHR calls that match a rule until their category is allowed.
+
+## Let visitors turn off one vendor
+
+A visitor can allow marketing and still switch off one vendor in it. Declare
+the vendors and pass them to `ConsentRoot` as `vendors`; helpers from
+`@c15t/integrations` already carry their vendor slug. See
+[vendor consent](https://c15t.com/docs/frameworks/next/vendor-consent).
+
+## Clear stored tracking data
+
+Script gating does not remove cookies or Web Storage entries a script already
+wrote. Pass `clearOnRevocation` to `ConsentRoot` to remove declared data when
+its category is denied. See
+[clear on revocation](https://c15t.com/docs/frameworks/next/clear-on-revocation) for
+configuration and browser limits.
+
+To send your own events only to allowed integrations, see
+[send events only to allowed integrations](../../integrations/overview.md#send-events-only-to-allowed-integrations).
+
+## Verify the integration
+
+Open the production build in a fresh browser session with DevTools open.
+
+1. Under an opt-in policy, neither PostHog nor X Pixel requests anything before
+   you choose.
+2. Open **Privacy settings** and turn on **Analytics** (the `measurement` category) only. PostHog loads and
+   X Pixel stays blocked.
+3. Reject, reload, and reopen **Privacy settings**. The rejection is still
+   selected and neither vendor loads.
+4. Turn a granted category off. The page reloads and that vendor does not load
+   again.
+
+The [runnable example](https://c15t.com/docs/examples) has the same script definitions, and
+[the consent checks](../../guides/verify-consent.md) cover the release checklist.

package/docs/frameworks/nuxt/embeds.md

@@ -0,0 +1,81 @@
+---
+title: Embeds
+description: Keep YouTube videos, maps and other iframes out of a Nuxt page
+  until their consent category is allowed, with ConsentGate or the iframe
+  blocker.
+group: frameworks
+---
+
+## Pick a method
+
+| Method             | Use it when                                                                                                                                    |
+| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| `ConsentGate`      | You render the iframe in a Vue component and want a placeholder with a way to open preferences. The server HTML respects the visitor's choice. |
+| The iframe blocker | The iframe comes from markup you do not render with a component, such as CMS content, or you want no wrapper.                                  |
+
+Both keep the iframe's `src` out of the page until the category is allowed,
+so the embed's host receives no request before consent.
+
+## Gate an embed with ConsentGate
+
+Wrap the iframe in the globally registered
+[`ConsentGate`](https://c15t.com/docs/frameworks/nuxt/components/consent-gate):
+
+```vue title="app/components/VideoEmbed.vue"
+<template>
+	<ConsentGate category="measurement">
+		<iframe
+			src="https://www.youtube-nocookie.com/embed/czTksCF6X8Y"
+			title="YouTube video"
+			loading="lazy"
+			allowfullscreen
+		/>
+		<template #placeholder>
+			<p>Allow measurement to load this YouTube video.</p>
+			<ConsentPreferencesLink>Choose video permissions</ConsentPreferencesLink>
+		</template>
+	</ConsentGate>
+</template>
+```
+
+The iframe is absent from the server HTML and the DOM until the visitor
+allows measurement. The `placeholder` slot shows a message and a
+[`ConsentPreferencesLink`](https://c15t.com/docs/frameworks/nuxt/components/consent-preferences-link)
+until then. When the visitor withdraws measurement, Vue removes the iframe.
+
+Pick the category that matches what the embed does. The example uses
+measurement for YouTube because its player measures views. A map or chat
+widget usually belongs under functionality or experience.
+
+## Gate an iframe with the iframe blocker
+
+The module runs the iframe blocker in the browser by default. Give an iframe
+`data-src` instead of `src`, and a `data-category`:
+
+```vue title="app/components/MapEmbed.vue"
+<template>
+	<iframe
+		data-src="https://www.google.com/maps/embed?pb=YOUR_EMBED_ID"
+		data-category="functionality"
+		title="Store map"
+	/>
+</template>
+```
+
+The server HTML has no `src`, so nothing loads before hydration. After
+hydration, c15t sets `src` from `data-src` when the category is allowed and
+removes it when the category is withdrawn. It watches the page, so iframes
+added by later navigation are handled too. The iframe element stays in the
+page while blocked, empty. Add `data-vendor` with a vendor ID to also block
+the iframe while the visitor has turned that vendor off.
+
+To turn the blocker off, set `iframeBlocker: false` in the module options.
+
+## Verify
+
+View the page source in a private window, under a policy that asks for
+consent. No iframe has a `src` pointing at `youtube-nocookie.com` or
+`google.com/maps`, and the Network tab shows no request to them. Allow the
+category and save: the iframe loads. Withdraw it and save: the page reloads
+without the embed. The [YouTube](../../integrations/youtube.md) and
+[Google Maps](../../integrations/google-maps.md) guides cover sizing and titles.