@c15t/scripts 3.0.0-alpha.1 → 3.0.0-alpha.3

package/docs/integrations/front-chat.md

@@ -0,0 +1,322 @@
+---
+title: Front Chat
+description: Load the Front Chat widget only after functionality consent with
+  the c15t frontChat helper, forward CSP nonces, clear the session on revocation
+  and check it in DevTools.
+icon: front-chat
+group: integrations
+---
+
+## Configure Front Chat
+
+Copy the `chatId` from the widget snippet in your Front Chat channel's
+**Installation** tab.
+
+| 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`     |
+
+```ts title="src/consent-scripts.ts"
+import { frontChat } from '@c15t/integrations/front-chat';
+
+export const scripts = [frontChat({ chatId: 'YOUR_FRONT_CHAT_ID' })];
+```
+
+## Register the scripts
+
+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 the vendor loads only through c15t.
+
+The vendor pages put the helper in `src/consent-scripts.ts`. If your framework
+quickstart already created a scripts file, such as `lib/scripts.ts` in the
+Next.js guide, add the helper to that array instead of creating a second file.
+The `scripts` export is a configuration, not an initializer. Add it to the c15t provider you already have, at the registration
+point for your framework below. These are edits to that provider, not a second
+provider.
+
+**Next.js**
+
+Import the configuration into the client boundary from your router guide:
+
+```ts
+import { ConsentRoot } from 'c15t/next';
+import { scripts } from './consent-scripts';
+```
+
+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
+<ConsentRoot state={state} config={consentConfig} scripts={scripts}>
+  {children}
+</ConsentRoot>
+```
+
+App Router, Pages Router and static export all use this `ConsentRoot` in
+the `'use client'` wrapper `components/consent.tsx`. Keep `scripts` there,
+because a Server Component cannot pass script callbacks to it. See
+[Next.js scripts and embeds](../frameworks/next/scripts.md).
+
+**TanStack Start**
+
+Import the configuration into your root route and pass it to the existing
+`ConsentRoot` as a top-level prop. Keep the loader, `backendURL` and
+`initRoute` from the [TanStack Start quickstart](https://c15t.com/docs/frameworks/tanstack-start/quickstart):
+
+```tsx title="src/routes/__root.tsx"
+import { scripts } from '../consent-scripts';
+
+<ConsentRoot
+  state={consent}
+  backendURL={backendURL}
+  initRoute={false}
+  scripts={scripts}
+>
+```
+
+Import vendor helpers in the root route module, not in a server function.
+A server function's return value must be serializable, and script
+configurations carry callbacks. See
+[TanStack Start scripts](../frameworks/tanstack-start/scripts.md).
+
+**React**
+
+Add the configuration to the existing `ConsentProvider` options, next to
+`mode`:
+
+```tsx title="src/consent.tsx"
+import { scripts } from './consent-scripts';
+
+<ConsentProvider options={{ mode, scripts }}>
+```
+
+`mode` is the `hosted({ url: 'https://your-project.inth.app' })` value
+from the [React quickstart](https://c15t.com/docs/frameworks/react/quickstart). Keep the banner,
+dialog and preferences link inside the provider. See
+[React scripts and embeds](../frameworks/react/scripts.md).
+
+**Nuxt**
+
+Register the scripts under the `c15t` key in `app/app.config.ts`. Adjust the
+relative import to where you created `consent-scripts.ts`:
+
+```ts title="app/app.config.ts"
+import { scripts } from '../src/consent-scripts';
+
+export default defineAppConfig({
+  c15t: { scripts },
+});
+```
+
+The Nuxt module merges this over its options in `nuxt.config.ts` and starts
+one script loader in the browser after hydration, once it has applied the
+visitor's stored choice and privacy signals. Keep `scripts` out of
+`nuxt.config.ts`, which reaches the browser as JSON and drops the vendor
+callbacks. Write the vendor IDs into `consent-scripts.ts`. See
+[Nuxt scripts and embeds](../frameworks/nuxt/scripts.md).
+
+**Vue**
+
+Pass the scripts to the existing `c15tVue` plugin call in `src/main.ts`:
+
+```ts title="src/main.ts"
+import { scripts } from './consent-scripts';
+
+app.use(c15tVue, {
+  backendURL: 'https://your-project.inth.app',
+  scripts,
+});
+```
+
+Keep your existing backend URL and other options. The plugin starts one
+script loader when the app mounts, after it has applied the visitor's stored
+choice. Do not also call `createScriptLoader` from a component. See
+[Vue scripts and embeds](../frameworks/vue/scripts.md).
+
+**Astro**
+
+Add the scripts to the client entrypoint from the
+[Astro quickstart](https://c15t.com/docs/frameworks/astro/quickstart), the module that the
+integration's `clientEntrypoint` option names. Keep `mode`, `ui` and the
+framework integration in `astro.config.mjs` as they are. If the module
+already exports scripts, combine the two arrays.
+
+```ts title="src/consent-client.ts"
+import type { C15tClientOptionsExtension } from 'c15t/astro';
+import { scripts } from './consent-scripts';
+
+export default { scripts } satisfies C15tClientOptionsExtension;
+```
+
+Vendor helpers contain callbacks, and the integration options in
+`astro.config.mjs` are serialized into the page, so do not put helpers in
+the integration's `scripts` option. The integration passes the client
+entrypoint to the one runtime every page shares, including across
+`ClientRouter` navigation.
+
+**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 mode = hosted({ url: 'https://your-project.inth.app' });
+</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: 'https://your-project.inth.app' });
+</script>
+
+<ConsentManagerProvider {mode} {scripts} prefetch={data.prefetch}>
+  {@render children()}
+  <!-- Keep your consent UI and preferences link here. -->
+</ConsentManagerProvider>
+```
+
+Import vendor helpers in the layout component, not in `+layout.server.ts`:
+a server load cannot send functions to the browser. Prerendered, static and
+SPA-mode pages use the same `scripts` prop. If you pass an externally owned
+`runtime` to the provider, register scripts when creating that runtime instead.
+
+**HTML**
+
+The helpers in `@c15t/integrations` are ES modules that need a bundler. On a
+page that loads the c15t script tag, paste the vendor's own snippet instead
+and keep it inert until its category is allowed:
+
+```html
+<script type="text/plain" data-c15t-category="measurement">
+  // The vendor's snippet, unchanged
+</script>
+```
+
+Use the category this guide names for the vendor. c15t runs the snippet
+once that category is allowed, and reloads the page when the visitor
+withdraws it. Helper options on this page, such as `loadMode`, do not apply
+to a pasted snippet. See [HTML scripts](../frameworks/html/scripts.md).
+
+**JavaScript**
+
+Pass the scripts to `init()` from `@c15t/browser`, next to your backend
+URL:
+
+```ts
+import { init } from '@c15t/browser';
+import { scripts } from './consent-scripts';
+
+const consent = init({
+  backendURL: 'https://your-project.inth.app',
+  scripts,
+});
+```
+
+Keep the backend URL from your quickstart. With
+`createConsentRuntime` from `c15t/runtime`, pass `scripts` to it instead.
+A kernel you create yourself needs a loader from
+`c15t/modules/script-loader`. Attach one loader per kernel. See
+[JavaScript scripts](../frameworks/javascript/scripts.md).
+
+## Options
+
+| Option               | Default                                              | Behavior                                                                                                                                              |
+| -------------------- | ---------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `chatId`             | Required                                             | Public chat ID passed to `FrontChat('init')`. Surrounding whitespace is trimmed; an empty value throws.                                               |
+| `useDefaultLauncher` | `true`                                               | Shows Front's launcher. With `false`, open the widget from your own launcher through Front's [SDK](https://dev.frontapp.com/docs/chat-sdk-reference). |
+| `nonce`              | None                                                 | CSP nonce for the loader and Front's generated scripts. A loader nonce from your consent provider is forwarded to `init` too.                         |
+| `scriptSrc`          | `https://chat-assets.frontapp.com/v1/chat.bundle.js` | Loader URL override. A proxy here does not proxy the widget's other requests.                                                                         |
+
+Front creates more resources for the widget. Follow Front's
+[CSP instructions](https://help.front.com/en/articles/2049) for the rest of the
+policy.
+
+## Loading and revocation
+
+`frontChat` uses the `functionality` category and appends its loader to
+`<body>` once functionality is allowed. After the SDK loads, the helper calls
+`FrontChat('init')` with your chat ID. If functionality is revoked while the
+SDK is still downloading, the helper skips `init`.
+
+On revocation the helper removes the loader element and calls no Front API.
+The running widget stays until c15t reloads the page, so keep
+`reloadOnConsentRevoked` enabled.
+
+## Clear the Front session on revocation
+
+The reload removes the widget but keeps the visitor's Front session. To clear
+it, call `shutdownFrontChat()` from the `onBeforeConsentRevocationReload`
+callback in your consent options:
+
+```ts title="src/consent-callbacks.ts"
+import { shutdownFrontChat } from '@c15t/integrations/front-chat';
+
+export const callbacks = {
+	onBeforeConsentRevocationReload: ({ preferences }) => {
+		if (!preferences.functionality) {
+			shutdownFrontChat();
+		}
+	},
+};
+```
+
+`shutdownFrontChat` sends `FrontChat('shutdown', { clearSession: true })` when
+the SDK has loaded and does nothing otherwise. Front returns no completion
+signal, so the reload does not wait for the session to clear.
+
+## Verify Front Chat
+
+After you allow functionality, `chat.bundle.js` loads and the widget connects
+to your Front inbox. With `shutdownFrontChat` wired, revoke functionality and
+check that the next grant starts a new Front session.
+
+Test in a private window with an opt-in policy. Open DevTools Network, disable
+the cache and filter by the vendor's domain:
+
+1. Load the page. No request goes to the vendor before you choose.
+2. Click Reject, then reload. There is still no vendor request.
+3. Open Privacy settings and allow the helper's category. The vendor script
+   loads without a page reload.
+4. Turn the category off again and save. c15t reloads the page, and the new
+   page makes no vendor request.
+
+c15t reloads on revocation because removing a script element does not stop
+code that already ran. The vendor's listeners, timers and queued events stay
+alive until the page unloads. If you set `reloadOnConsentRevoked: false`, stop
+the vendor yourself. Register a callback-only script whose `onConsentChange`
+calls the vendor's opt-out API, as shown in
+[custom integrations](./building-integrations.md), and check the
+permission before each of your own event calls. The reload does not delete
+cookies the vendor already set; see
+[clear on revocation for your framework](./overview.md#vendor-switches-and-cookie-cleanup).
+
+The helper sets `vendor` to its script ID, so once you declare that vendor a
+visitor can turn it off inside an allowed category. See
+[vendor consent for your framework](./overview.md#vendor-switches-and-cookie-cleanup). The
+[consent verification guide](../guides/verify-consent.md) covers navigation,
+expiry and hosting checks.

package/docs/integrations/google-maps.md

@@ -1,6 +1,9 @@
 ---
 title: Google Maps
-description: Prevent a map iframe from mounting before the required permission.
+description: Gate a Google Maps iframe embed with c15t v3 so the map loads only
+  after the visitor allows its consent category, in Next.js, TanStack Start,
+  React, Nuxt, Vue, Astro, Svelte, SvelteKit, HTML or JavaScript.
+icon: google-maps
 group: integrations
 ---
 
@@ -11,7 +14,8 @@ application; this example uses functionality permission.
 
 ```ts title="src/embed-config.ts"
 export const embedCategory = 'functionality' as const;
-export const embedURL = 'https://www.google.com/maps/embed?pb=YOUR_EMBED_PARAMETERS';
+export const embedURL =
+	'https://www.google.com/maps/embed?pb=YOUR_EMBED_PARAMETERS';
 export const embedTitle = 'Map showing our office location';
 export const embedAspectRatio = '4 / 3';
 ```
@@ -107,64 +111,66 @@ on revocation. Keep your existing consent styles and preferences dialog.
 
 **Nuxt**
 
-Use the reactive snapshot from the existing consent runtime. The Nuxt module auto-imports the consent composables.
+The Nuxt module registers `ConsentGate` and `ConsentPreferencesLink`, so
+this component imports only the embed configuration.
 
 ```vue title="app/components/ConsentEmbed.vue"
 <script setup lang="ts">
 import { embedCategory, embedURL, embedTitle, embedAspectRatio } from '../../src/embed-config';
-
-const snapshot = useConsentSnapshot();
-const activeUI = useConsentActiveUI();
 </script>
 
 <template>
-  <iframe
-    v-if="snapshot.effectivePermissions[embedCategory]"
-    :src="embedURL"
-    :title="embedTitle"
-    loading="lazy"
-    allowfullscreen
-    :style="{ width: '100%', aspectRatio: embedAspectRatio, minHeight: '200px', border: 0 }"
-  />
-  <button v-else type="button" @click="activeUI = 'manager'">
-    Open privacy settings to view this content
-  </button>
+  <ConsentGate :category="embedCategory">
+    <iframe
+      :src="embedURL"
+      :title="embedTitle"
+      loading="lazy"
+      allowfullscreen
+      :style="{ width: '100%', aspectRatio: embedAspectRatio, minHeight: '200px', border: 0 }"
+    />
+    <template #placeholder>
+      <p>Allow {{ embedCategory }} to load this content.</p>
+      <ConsentPreferencesLink>Open privacy settings</ConsentPreferencesLink>
+    </template>
+  </ConsentGate>
 </template>
 ```
 
-Use `v-if` so a denied iframe is removed from the DOM. Hiding an existing
-iframe with `v-show` or CSS does not prevent its requests.
+`ConsentGate` keeps the iframe out of the server HTML and the DOM while
+permission is denied, and removes it on revocation. See
+[Nuxt scripts and embeds](../frameworks/nuxt/scripts.md).
 
 **Vue**
 
-Use the reactive snapshot from the existing consent runtime. The c15t Vue plugin must already be installed on this app.
+Render this component inside the app that installed the c15t Vue plugin.
 
 ```vue title="src/ConsentEmbed.vue"
 <script setup lang="ts">
-import { useConsentSnapshot, useConsentActiveUI } from 'c15t/vue/vue-plugin';
+import ConsentGate from 'c15t/vue/runtime/components/consent-gate.vue';
+import ConsentPreferencesLink from 'c15t/vue/runtime/components/consent-preferences-link.vue';
 import { embedCategory, embedURL, embedTitle, embedAspectRatio } from './embed-config';
-
-const snapshot = useConsentSnapshot();
-const activeUI = useConsentActiveUI();
 </script>
 
 <template>
-  <iframe
-    v-if="snapshot.effectivePermissions[embedCategory]"
-    :src="embedURL"
-    :title="embedTitle"
-    loading="lazy"
-    allowfullscreen
-    :style="{ width: '100%', aspectRatio: embedAspectRatio, minHeight: '200px', border: 0 }"
-  />
-  <button v-else type="button" @click="activeUI = 'manager'">
-    Open privacy settings to view this content
-  </button>
+  <ConsentGate :category="embedCategory">
+    <iframe
+      :src="embedURL"
+      :title="embedTitle"
+      loading="lazy"
+      allowfullscreen
+      :style="{ width: '100%', aspectRatio: embedAspectRatio, minHeight: '200px', border: 0 }"
+    />
+    <template #placeholder>
+      <p>Allow {{ embedCategory }} to load this content.</p>
+      <ConsentPreferencesLink>Open privacy settings</ConsentPreferencesLink>
+    </template>
+  </ConsentGate>
 </template>
 ```
 
-Use `v-if` so a denied iframe is removed from the DOM. Hiding an existing
-iframe with `v-show` or CSS does not prevent its requests.
+`ConsentGate` keeps the iframe out of the DOM while permission is denied,
+and removes it on revocation. See
+[Vue scripts and embeds](../frameworks/vue/scripts.md).
 
 **Astro**
 
@@ -175,7 +181,7 @@ Add this component to pages using your consent-enabled base layout:
 <c15t-consent-embed style="display: block"></c15t-consent-embed>
 
 <script>
-  import { getConsentClient } from '@c15t/astro/client';
+  import { getConsentClient } from 'c15t/astro/client';
   import { mountConsentEmbed } from '../consent-embed';
 
   class ConsentEmbed extends HTMLElement {
@@ -273,16 +279,37 @@ The Svelte `ConsentGate` waits until the browser is mounted and the category is
 allowed. Its default placeholder opens preferences. Revocation removes the
 iframe.
 
+**HTML**
+
+The c15t script tag gates iframes that name a category. Put the embed's URL
+in `data-src` instead of `src`, using the values from the configuration on
+this page:
+
+```html
+<iframe
+  data-src="https://www.youtube-nocookie.com/embed/VIDEO_ID?playsinline=1"
+  data-category="measurement"
+  title="Product video"
+  loading="lazy"
+  allowfullscreen
+></iframe>
+```
+
+c15t sets `src` once the category is allowed and removes it on revocation.
+Without `src` the iframe loads nothing, so hide it with CSS and show a link
+to `#c15t-preferences` in its place. See
+[HTML embeds](../frameworks/html/embeds.md).
+
 **JavaScript**
 
-Use the shared browser helper below with your existing kernel. Put an
+Use the shared browser helper below with your existing client. Put an
 empty container where the embed should appear:
 
 ```html
 <div id="consent-embed"></div>
 ```
 
-In your browser entry point, after creating the kernel:
+In your browser entry point, after `init()`:
 
 ```ts
 import { mountConsentEmbed } from './consent-embed';
@@ -290,13 +317,16 @@ import { mountConsentEmbed } from './consent-embed';
 const container = document.querySelector<HTMLElement>('#consent-embed');
 if (!container) throw new Error('Missing consent embed container');
 
-const disposeEmbed = mountConsentEmbed(container, kernel, openPreferences);
+const disposeEmbed = mountConsentEmbed(container, consent.kernel, () =>
+  consent.openDialog(),
+);
 ```
 
-`kernel` is the instance from your quickstart. `openPreferences` is your
-application's function for showing its consent preferences UI. Call
-`disposeEmbed()` when the page or component is destroyed. The helper observes
-both the current snapshot and later changes.
+`consent` is the client from `init()` in your quickstart. With
+`createConsentRuntime`, pass `runtime.kernel` and your own function that
+opens preferences. Call `disposeEmbed()` when the page or component is
+destroyed. Iframe markup with `data-src` and `data-category` also works
+without the helper, because both setups gate iframes by default.
 
 ## Browser helper for Astro and JavaScript
 
@@ -305,51 +335,56 @@ when permission allows it, keeps an existing player mounted across unrelated
 snapshot updates, and removes it on revocation.
 
 ```ts title="src/consent-embed.ts"
-import { embedCategory, embedURL, embedTitle, embedAspectRatio } from './embed-config';
+import {
+	embedCategory,
+	embedURL,
+	embedTitle,
+	embedAspectRatio,
+} from './embed-config';
 
 type EmbedKernel = {
-  getSnapshot: () => {
-    effectivePermissions: Record<typeof embedCategory, boolean>;
-  };
-  subscribe: (listener: () => void) => () => void;
+	getSnapshot: () => {
+		effectivePermissions: Record<typeof embedCategory, boolean>;
+	};
+	subscribe: (listener: () => void) => () => void;
 };
 
 export function mountConsentEmbed(
-  container: HTMLElement,
-  kernel: EmbedKernel,
-  openPreferences: () => void,
+	container: HTMLElement,
+	kernel: EmbedKernel,
+	openPreferences: () => void
 ) {
-  const render = () => {
-    if (kernel.getSnapshot().effectivePermissions[embedCategory]) {
-      if (container.querySelector('iframe')) return;
-      const frame = document.createElement('iframe');
-      frame.src = embedURL;
-      frame.title = embedTitle;
-      frame.loading = 'lazy';
-      frame.allowFullscreen = true;
-      Object.assign(frame.style, {
-        width: '100%',
-        aspectRatio: embedAspectRatio,
-        minHeight: '200px',
-        border: '0',
-      });
-      container.replaceChildren(frame);
-    } else {
-      if (container.querySelector('button')) return;
-      const button = document.createElement('button');
-      button.type = 'button';
-      button.textContent = 'Open privacy settings to view this content';
-      button.onclick = openPreferences;
-      container.replaceChildren(button);
-    }
-  };
-
-  render();
-  const unsubscribe = kernel.subscribe(render);
-  return () => {
-    unsubscribe();
-    container.replaceChildren();
-  };
+	const render = () => {
+		if (kernel.getSnapshot().effectivePermissions[embedCategory]) {
+			if (container.querySelector('iframe')) return;
+			const frame = document.createElement('iframe');
+			frame.src = embedURL;
+			frame.title = embedTitle;
+			frame.loading = 'lazy';
+			frame.allowFullscreen = true;
+			Object.assign(frame.style, {
+				width: '100%',
+				aspectRatio: embedAspectRatio,
+				minHeight: '200px',
+				border: '0',
+			});
+			container.replaceChildren(frame);
+		} else {
+			if (container.querySelector('button')) return;
+			const button = document.createElement('button');
+			button.type = 'button';
+			button.textContent = 'Open privacy settings to view this content';
+			button.onclick = openPreferences;
+			container.replaceChildren(button);
+		}
+	};
+
+	render();
+	const unsubscribe = kernel.subscribe(render);
+	return () => {
+		unsubscribe();
+		container.replaceChildren();
+	};
 }
 ```