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

package/docs/frameworks/astro/scripts.md

@@ -0,0 +1,155 @@
+---
+title: Scripts
+description: Load vendor scripts and gated inline scripts on an Astro site only
+  after the visitor allows their consent category, and stop them when consent is
+  withdrawn.
+group: frameworks
+---
+
+## Register vendor scripts
+
+The `ConsentBanner` component does not stop a `<script>` tag you already have.
+Give c15t each vendor script to load instead, and remove the vendor's own
+snippet so it loads once.
+
+Vendor helpers from `@c15t/integrations` contain callbacks, and the integration
+options in `astro.config.mjs` must survive JSON serialization. So register
+helpers in the module that the integration's `clientEntrypoint` option names.
+This list loads PostHog on measurement and X Pixel on marketing:
+
+```ts title="src/example-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',
+		region: 'eu',
+	}),
+	xPixel({ pixelId: 'your-pixel-id' }),
+];
+```
+
+```ts title="src/consent-client.ts"
+import type { C15tClientOptionsExtension } from 'c15t/astro';
+
+import { scripts } from './example-scripts';
+
+export default { scripts } satisfies C15tClientOptionsExtension;
+```
+
+The integration imports that module into the page's boot script, so every page
+shares one script loader. Each helper's guide under
+[integrations](../../integrations/overview.md) lists its options and the requests
+to expect.
+
+## Add a script without a helper
+
+A script with no callbacks can go straight into the integration options. Give
+it an `id`, a `category`, and either a `src` or inline `textContent`:
+
+```js title="astro.config.mjs (partial)"
+c15t({
+	mode: hosted({ url: 'https://your-project.inth.app' }),
+	scripts: [
+		{
+			id: 'example-analytics',
+			category: 'measurement',
+			src: 'https://analytics.example.com/script.js',
+		},
+	],
+});
+```
+
+Scripts from `astro.config.mjs` and from the client entrypoint both load.
+
+## What a site without scripts skips
+
+The script loader is part of the page's boot script only when the site
+configures `scripts` in `astro.config.mjs` or sets a `clientEntrypoint`, which
+may add some. A site with neither never downloads it, about 4 KB gzip less on
+every page. The [network blocker](./network-blocker.md) works the same way: it
+ships in the boot script when the integration options have `networkBlocker`
+rules, and loads as its own chunk when only the client entrypoint sets them.
+
+## Gate an inline script
+
+For a script that has to stay in the page's markup, make it inert and label it
+with a category. c15t runs it once the category is allowed:
+
+```astro title="src/pages/index.astro (partial)"
+<script data-c15t-category="measurement" is:inline type="text/plain">
+	document.getElementById('inline-script-status').textContent =
+		'Measurement script ran';
+</script>
+```
+
+Three attributes matter:
+
+* `type="text/plain"` stops the browser from running the script.
+* `data-c15t-category` names one category. An unknown name logs a warning and
+  the script never runs.
+* `is:inline` makes Astro ship the tag as written. Without it, Astro bundles the
+  script and runs it regardless of consent.
+
+Add `data-c15t-vendor` with a vendor slug to also hold the script while the
+visitor has switched that vendor off. See
+[vendor consent](https://c15t.com/docs/frameworks/astro/vendor-consent).
+
+Under a nonce-based Content Security Policy, where your middleware sets
+`Astro.locals.c15t.nonce`, also add `nonce={Astro.locals.c15t?.nonce}` to the
+tag. c15t then activates only gated tags that carry the page's nonce, and
+skips the rest with a console warning. See
+[put the nonce on your gated scripts](https://c15t.com/docs/frameworks/astro/content-security-policy#put-the-nonce-on-your-gated-scripts).
+
+c15t checks gated scripts when the page loads, after each consent change and
+after each `ClientRouter` navigation, so a script on a page you navigate to
+runs as soon as it is allowed. A script with `src` works the same way. For
+markup you insert later from your own code, call
+`activateGatedScripts(getConsent(), container)` from `c15t/astro/client`.
+Under a nonce policy, give the inserted tags the nonce and pass it as a third
+argument.
+
+A script that has run cannot be undone. When the visitor withdraws consent,
+c15t reloads the page, and the reloaded page leaves the script inert.
+
+## Gate embeds and requests
+
+An iframe loads as soon as it is in the page, so gate embeds separately. See
+[Embeds](./embeds.md) for a component that renders an iframe
+only while its category is allowed, and for the iframe blocker.
+
+To stop `fetch` and `XMLHttpRequest` calls to tracking hosts until consent,
+add rules to `networkBlocker`. See
+[Network blocker](./network-blocker.md).
+
+## Clear data when consent is withdrawn
+
+Set `clearOnRevocation` in the integration options to remove a vendor's
+cookies and storage keys when its category is withdrawn. See
+[clear on revocation](https://c15t.com/docs/frameworks/astro/clear-on-revocation) for the shape.
+
+## Withdraw consent without reloading
+
+By default c15t reloads the page after a save turns off a category that was
+allowed, because it cannot stop code that has already run. Set
+`reloadOnConsentRevoked: false` in the integration options only if every script
+on the page stops itself when its category is withdrawn. Stop your own code
+from the `onPermissionsChanged` callback. See
+[Callbacks](https://c15t.com/docs/frameworks/astro/callbacks).
+
+## Check script loading
+
+Build the site and open it in a private window with DevTools Network open:
+
+1. Before you choose, filter for each vendor's domain. There are no requests,
+   and a gated inline script has not run.
+2. Allow one category from **Cookie preferences**. Only that category's vendors
+   load, and inline scripts gated on it run.
+3. Reload. The allowed vendors load again, and the others stay absent.
+4. Withdraw the category and save. The page reloads and the vendor does not
+   load.
+
+See [Verify consent](../../guides/verify-consent.md) for the full checklist.

package/docs/frameworks/html/embeds.md

@@ -0,0 +1,142 @@
+---
+title: Embeds
+description: Hold YouTube videos, maps and other iframes on a plain HTML page
+  until their consent category is allowed with data-src and data-category, show
+  a placeholder, and configure the c15t iframe blocker.
+group: frameworks
+---
+
+## Gate an iframe
+
+Move the iframe's URL from `src` to `data-src` and name its category in
+`data-category`. The c15t script tag gives the iframe its `src` once the
+category is allowed:
+
+```html title="index.html"
+<iframe
+	data-src="https://www.youtube-nocookie.com/embed/czTksCF6X8Y?playsinline=1"
+	data-category="measurement"
+	data-vendor="youtube"
+	title="YouTube video"
+	allow="encrypted-media; picture-in-picture"
+	allowfullscreen
+></iframe>
+```
+
+An iframe with no `src` loads nothing, so the vendor gets no request and sets
+no cookie until the visitor allows the category. Give every embed a `title`
+that says what it shows.
+
+## Attributes
+
+| Attribute          | What it does                                                                                                                                                                                         |
+| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `data-src`         | The embed's URL. c15t moves it to `src` when the gate opens. Only `http:` and `https:` URLs load. A relative URL resolves against the page.                                                          |
+| `data-category`    | One category name. An unknown name logs a warning and keeps the iframe blocked.                                                                                                                      |
+| `data-vendor`      | Optional vendor ID for vendor-level consent. The iframe also stays blocked while the visitor has turned that vendor off. See [vendor consent](https://c15t.com/docs/frameworks/html/vendor-consent). |
+| `data-c15t-paused` | Set by c15t when it took away a `src` the iframe already had. Do not set it yourself.                                                                                                                |
+
+Iframes without `data-category` or `data-vendor` are left alone.
+
+## Show a placeholder
+
+c15t does not draw anything in place of a blocked iframe. Put your own message
+next to it and hide it once the iframe has a `src`. The quickstart page uses
+this markup:
+
+```html
+<div class="embed">
+  <iframe data-src="…" data-category="measurement" title="YouTube video"></iframe>
+  <div class="placeholder">
+    <p>Allow measurement to load this YouTube video.</p>
+    <a href="#c15t-preferences">Choose video permissions</a>
+  </div>
+</div>
+```
+
+```css
+.embed iframe:not([src]) { display: none; }
+.embed iframe[src] + .placeholder { display: none; }
+```
+
+The `#c15t-preferences` link opens the preference dialog, where the visitor
+can allow the category. See [preferences link](https://c15t.com/docs/frameworks/html/components/preferences-link).
+
+## What happens on withdrawal
+
+When a visitor turns the category off, c15t removes the iframe's `src` and puts
+the URL back in `data-src`, which unloads the embed. The page also reloads by
+default, as it does for scripts.
+
+An iframe written with a normal `src` and a `data-category` starts loading
+before c15t runs, then c15t removes the `src`. The vendor already got its
+request, so always use `data-src`.
+
+## Iframes added later
+
+c15t watches the whole document. An iframe that a page builder, a CMS widget
+or your own script adds later is gated the moment it appears, and so is an
+iframe whose `data-category` changes. This keeps working when a client router
+such as Turbo replaces `<body>` on navigation, and when the c15t tag runs in
+`<head>` before `<body>` exists.
+
+## Configure the iframe blocker
+
+The iframe blocker is on by default in every `@c15t/browser` build. Set
+`iframeBlocker` in a queued `config` call to change it:
+
+```html
+<script>
+  window.c15t = window.c15t || [];
+  c15t.push(['config', { iframeBlocker: false }]);
+</script>
+```
+
+| Value                                | Effect                                                                                                                                                         |
+| ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| omitted or `{}`                      | Gate every iframe with `data-category` or `data-vendor`, including ones added later.                                                                           |
+| `{ disableAutomaticBlocking: true }` | Do not scan or watch the page. c15t sets or removes a `src` only when you call `c15t.processIframes()`. See [check iframes yourself](#check-iframes-yourself). |
+| `false`                              | Turn the blocker off. `data-src` iframes never load.                                                                                                           |
+
+The categories on gated iframes are added to the preference dialog, as they
+are for gated scripts.
+
+## Check iframes yourself
+
+With `iframeBlocker: { disableAutomaticBlocking: true }`, c15t leaves iframes
+alone until your page calls `c15t.processIframes()`. Each call pauses gated
+iframes, those with `data-category` or `data-vendor`, that consent does not
+allow, and restores the ones it does. Call it after the policy resolves, after
+you add iframes, and after consent changes:
+
+```html
+<script>
+  window.c15t = window.c15t || [];
+  c15t.push(['config', { iframeBlocker: { disableAutomaticBlocking: true } }]);
+  c15t.push(['processIframes']);
+  c15t.push(['on', 'consent', () => c15t.processIframes()]);
+</script>
+```
+
+A queued `processIframes` runs once the policy has resolved, so
+`c15t.push(['processIframes'])` is safe before and after the tag loads. With
+automatic blocking on, c15t does this by itself and you do not need to call
+it.
+
+## Vendor embeds
+
+The [integration guides](../../integrations/overview.md) have an HTML tab for
+YouTube, Google Maps and other embeds, with the category each one needs. The
+`youtube-nocookie.com` player still contacts Google when it loads, so gate it
+like any other embed.
+
+## Check it works
+
+Open the page in a private window with the Network tab open.
+
+1. Before you choose, the iframe has no `src` in the Elements panel and there
+   is no request to the embed's host. The placeholder shows.
+2. Allow the category. The iframe gets its `src`, the embed loads and the
+   placeholder hides.
+3. Open preferences and turn the category off. The page reloads and the embed
+   stays unloaded.

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

@@ -0,0 +1,105 @@
+---
+title: Network blocker
+description: Hold fetch and XMLHttpRequest calls from a plain HTML page until
+  their consent category is allowed, with network blocker rules queued on the
+  c15t script tag.
+group: frameworks
+---
+
+## When you need it
+
+Some code sends data with `fetch` or `XMLHttpRequest` from a place you cannot
+change into a `text/plain` tag, such as a theme's bundled script, a plugin, or your own
+code that runs before consent. A network blocker rule holds those requests
+until the rule's category is allowed. Script tags and iframes do not need it;
+gate those with [gated scripts](https://c15t.com/docs/frameworks/html/components/gated-script)
+and [embeds](./embeds.md).
+
+## Add rules
+
+Queue a `config` call with `networkBlocker` before the script tag:
+
+```html
+<script>
+  window.c15t = window.c15t || [];
+  c15t.push(['config', {
+    networkBlocker: {
+      rules: [
+        { id: 'collector', domain: 'collect.example.com', category: 'measurement' },
+        {
+          id: 'events',
+          domain: 'example.com',
+          pathIncludes: '/api/track',
+          methods: ['POST'],
+          category: 'measurement',
+        },
+      ],
+      onRequestBlocked: ({ method, url, rule }) => {
+        console.info('c15t blocked', method, url, rule?.id);
+      },
+    },
+  }]);
+</script>
+```
+
+The first rule blocks every request to `collect.example.com` and its
+subdomains until measurement is allowed. The second blocks only POST requests
+to paths on `example.com` that contain `/api/track`.
+
+## Rule fields
+
+| Field                                                                | Required | What it does                                                                                                             |
+| -------------------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------ |
+| `domain`                                                             | Yes      | The host to match. Subdomains match too: `example.com` covers `www.example.com`.                                         |
+| `category`                                                           | Yes      | The category that lets matching requests through. A condition such as `{ and: ['measurement', 'marketing'] }` works too. |
+| `pathIncludes`                                                       | No       | Match only URLs whose path contains this text.                                                                           |
+| `methods`                                                            | No       | Match only these HTTP methods, such as `['POST']`. All methods when omitted.                                             |
+| `id`                                                                 | No       | A name for the rule, shown in logs and passed to `onRequestBlocked`.                                                     |
+| `vendor`                                                             | No       | Also block while the visitor has turned this vendor off.                                                                 |
+| `vendorId`, `iabPurposes`, `iabLegIntPurposes`, `iabSpecialFeatures` | No       | IAB TCF conditions, checked only under an IAB policy.                                                                    |
+
+## Blocker options
+
+| Option               | Default  | What it does                                                  |
+| -------------------- | -------- | ------------------------------------------------------------- |
+| `rules`              | required | The rules above.                                              |
+| `enabled`            | `true`   | `false` keeps the configuration but blocks nothing.           |
+| `logBlockedRequests` | `true`   | Log each blocked request with `console.warn`.                 |
+| `onRequestBlocked`   | none     | Called with `{ method, url, rule }` for each blocked request. |
+
+## What a blocked request sees
+
+* A blocked `fetch` resolves with a `451` response. It does not reject, so
+  check `response.ok` in code that expects data.
+* A blocked `XMLHttpRequest` fires an `error` event.
+* A request sent before the policy resolves waits, then goes out or is
+  blocked once c15t knows the visitor's permissions. If the policy fails to
+  load, it is blocked.
+* A request that does not match any rule goes out at once.
+
+The rules' categories are added to the preference dialog, as they are for
+gated scripts.
+
+## What it cannot block
+
+The network blocker patches `fetch` and `XMLHttpRequest` after the script tag
+runs. It does not cover:
+
+* `navigator.sendBeacon`, WebSockets and `EventSource`;
+* requests from `<img>`, `<script>`, `<link>` and `<iframe>` elements;
+* requests sent before the c15t tag ran. With `defer`, the tag runs after the
+  page has parsed, so inline scripts anywhere in the page run before it;
+* requests from other frames and from service workers.
+
+Use gated tags for scripts and iframes. When inline code sends requests while
+the page parses, load the c15t tag without `defer` at the top of `<head>`, so
+it runs first. The banner still waits for the document to parse before it
+mounts.
+
+## Check it works
+
+1. Open the page in a private window with the console and Network tab open.
+2. Trigger the request, for example by loading the page that sends it. The
+   console shows `[c15t] blocked POST https://example.com/api/track (rule: events)`
+   and the Network tab shows no request.
+3. Allow measurement and trigger it again. The request goes out.

package/docs/frameworks/html/scripts.md

@@ -0,0 +1,164 @@
+---
+title: Scripts
+description: Hold vendor scripts on a plain HTML page until the visitor allows
+  their category, load scripts with callbacks, handle withdrawal and clear
+  vendor cookies with the c15t script tag and no build step.
+group: frameworks
+---
+
+## Choose how to gate a script
+
+The c15t script tag has two ways to hold a vendor script until its category is
+allowed:
+
+| Form                                                               | Use it when                                                                                        |
+| ------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------- |
+| A `<script type="text/plain" data-c15t-category>` tag in your HTML | You paste a vendor snippet into a theme, a CMS field or a page builder. No JavaScript of your own. |
+| A `scripts` entry in a queued `config` call                        | You need a callback after the vendor loads, on an error, or when consent changes.                  |
+
+Both wait for the same permission and both add their category to the
+preference dialog. Iframes use `data-src` instead; see
+[embeds](./embeds.md). Requests your own code sends with
+`fetch` use the [network blocker](./network-blocker.md).
+
+## Gate a pasted snippet
+
+Change the vendor's tag to `type="text/plain"` and add
+`data-c15t-category`:
+
+```html
+<script type="text/plain" data-c15t-category="measurement">
+  // The vendor's snippet, unchanged
+</script>
+<script type="text/plain" data-c15t-category="marketing" src="https://vendor.example/tag.js"></script>
+```
+
+On a page whose c15t tag has a nonce, add the same `nonce` to each gated tag,
+or c15t skips it. See
+[gated tags on a page with a nonce](https://c15t.com/docs/frameworks/html/components/gated-script#gated-tags-on-a-page-with-a-nonce).
+The [quickstart](https://c15t.com/docs/frameworks/html/quickstart#gate-your-vendor-scripts)
+shows this with PostHog and X Pixel. [Gated scripts](https://c15t.com/docs/frameworks/html/components/gated-script)
+covers load order, copied attributes and tags added after load.
+
+## What happens when a visitor withdraws permission
+
+A script that has run cannot be stopped. When a visitor turns off a category
+they had allowed, c15t saves the choice and reloads the page. The new page
+starts with the vendor tag inert again. Allowing a category never reloads.
+
+To handle withdrawal yourself, for example by calling a vendor's opt-out
+function, set `reloadOnConsentRevoked: false` in `config`. Then c15t does not
+reload and the vendor code that already ran keeps running until the next page
+load. `callbacks.onBeforeConsentRevocationReload` runs right before the
+reload, if you need to flush something first. See
+[events and callbacks](https://c15t.com/docs/frameworks/html/callbacks).
+
+## Load a script with callbacks
+
+List the script under `scripts` in a queued `config` call before the tag:
+
+```html
+<script>
+  window.c15t = window.c15t || [];
+  c15t.push(['config', {
+    scripts: [
+      {
+        id: 'analytics',
+        src: 'https://analytics.example/sdk.js',
+        category: 'measurement',
+        onLoad: () => window.analytics.track('page_view'),
+        onConsentChange: ({ hasConsent }) => {
+          if (!hasConsent) window.analytics.optOut();
+        },
+      },
+    ],
+  }]);
+</script>
+```
+
+`analytics.track` and `analytics.optOut` stand for your vendor's own API.
+c15t adds the script to `<head>` once measurement is allowed, and removes the
+element again when the visitor withdraws it.
+
+| Field                                                    | What it does                                                                                                                           |
+| -------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
+| `id`                                                     | A unique, stable name for the script. Required.                                                                                        |
+| `category`                                               | The category it needs, such as `'measurement'`. Required. It also accepts a condition such as `{ and: ['measurement', 'marketing'] }`. |
+| `src` or `textContent`                                   | The URL to load, or inline code to run. One is required unless `callbackOnly` is set.                                                  |
+| `callbackOnly`                                           | Add no element. Only run the callbacks, for a vendor that is already on the page.                                                      |
+| `alwaysLoad`                                             | Load whatever the consent state. Use it only for tags that manage consent themselves.                                                  |
+| `persistAfterConsentRevoked`                             | Keep the element on the page after withdrawal.                                                                                         |
+| `target`                                                 | `'head'` (default) or `'body'`.                                                                                                        |
+| `async`, `defer`, `nonce`, `fetchPriority`, `attributes` | Attributes for the created `<script>` element. Without its own `nonce`, the script gets the c15t tag's nonce.                          |
+| `anonymizeId`                                            | Give the element a random `id` so blockers cannot match it by name. On by default.                                                     |
+| `vendor`                                                 | A vendor ID for vendor-level consent. See [vendor consent](https://c15t.com/docs/frameworks/html/vendor-consent).                      |
+| `onBeforeLoad`, `onLoad`, `onError`                      | Run before a load attempt, after the script loads, or when it fails.                                                                   |
+| `onConsentChange`                                        | Run each time the script's consent changes. The argument has `hasConsent` and `consents`.                                              |
+| `onDispose`                                              | Run when the script is removed from the configuration or c15t is disposed.                                                             |
+
+Every callback receives the script's `id`, the created element's
+`elementId`, `hasConsent`, the current `consents`, and the `element` when
+there is one.
+
+For a plain vendor snippet, the `text/plain` tag is simpler and works in any
+CMS field that accepts HTML. The vendor helpers in `@c15t/integrations`, such as
+the PostHog and Google tag helpers, are ES modules that need a bundler. On a
+plain HTML page, paste the vendor's own snippet into a `text/plain` tag.
+
+## Clear cookies when permission is withdrawn
+
+Gating stops new requests but does not delete what a vendor already stored.
+Add `clearOnRevocation` to the config to delete named cookies and storage keys
+when their category is denied. See
+[clear on revocation](https://c15t.com/docs/frameworks/html/clear-on-revocation).
+
+## Google Consent Mode and tag managers
+
+The script tag does not send Google Consent Mode signals. The Google tag and
+Google Tag Manager helpers in `@c15t/integrations` do, but they need a bundler. On
+a plain HTML page, gate Google's snippet like any other vendor. Google then
+loads only after consent, so it sends nothing before a choice.
+[Gated scripts](https://c15t.com/docs/frameworks/html/components/gated-script#load-order)
+shows the GA4 snippet with its two tags in the right order.
+
+If you need Consent Mode instead, load Google's snippet ungated and send the
+signals yourself. Put this before Google's tags:
+
+```html
+<script>
+  window.dataLayer = window.dataLayer || [];
+  function gtag() { dataLayer.push(arguments); }
+  gtag('consent', 'default', {
+    analytics_storage: 'denied',
+    ad_storage: 'denied',
+    ad_user_data: 'denied',
+    ad_personalization: 'denied',
+  });
+  window.c15t = window.c15t || [];
+  c15t.push(['on', 'consent', (snapshot) => {
+    const allowed = snapshot.effectivePermissions;
+    const state = (granted) => (granted ? 'granted' : 'denied');
+    gtag('consent', 'update', {
+      analytics_storage: state(allowed.measurement),
+      ad_storage: state(allowed.marketing),
+      ad_user_data: state(allowed.marketing),
+      ad_personalization: state(allowed.marketing),
+    });
+  }]);
+</script>
+```
+
+With Consent Mode, Google receives requests before a choice, marked as denied.
+Decide which behavior your policy needs before you pick one.
+
+The vendor guides under [integrations](../../integrations/overview.md) have an
+HTML tab with the no-build setup.
+
+## Check it works
+
+Open the page in a private window with the Network tab open.
+
+1. Filter for each vendor's domain. Nothing loads before a choice.
+2. Allow one category. Only that category's vendors load, and each `onLoad`
+   runs.
+3. Turn the category off again. The page reloads and the vendor stays absent.