@c15t/react 3.1.0 → 3.2.0

package/docs/integrations/customer-io.md

@@ -0,0 +1,369 @@
+---
+title: Customer.io
+description: Load Customer.io Data Pipelines only after marketing consent with
+  the c15t customerIo helper, set up a proxy, and check withdrawal.
+seoTitle: Customer.io cookie consent with c15t
+seoDescription: Load Customer.io only with marketing consent. Set your write
+  key, region and proxy, and reset identity on withdrawal with c15t.
+icon: chart-line
+group: integrations
+---
+
+Customer.io collects events and visitor identity on your site through its
+Data Pipelines JavaScript source, for use in its messaging. The c15t
+`customerIo` helper waits for `marketing` consent before it creates the
+`cioanalytics` global or downloads the SDK.
+
+When the visitor withdraws, the helper calls `cioanalytics.reset()` to clear
+the stored identity, and c15t reloads the page. `reset()` is not an opt-out.
+The reload is what stops the SDK.
+
+## Configure Customer.io
+
+Create a JavaScript source in Customer.io Data Pipelines and copy its write
+key. Note the region of your workspace. Then remove the original Customer.io
+snippet from your site, so that c15t controls when it loads.
+
+| Package manager | Command                          |
+| :-------------- | :------------------------------- |
+| npm             | `npm install @c15t/integrations` |
+| pnpm            | `pnpm add @c15t/integrations`    |
+| yarn            | `yarn add @c15t/integrations`    |
+| bun             | `bun add @c15t/integrations`     |
+
+```ts title="src/consent-scripts.ts"
+import { customerIo } from '@c15t/integrations/customer-io';
+
+export const scripts = [customerIo({ writeKey: 'YOUR_WRITE_KEY' })];
+```
+
+## 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 has a `scripts` array, such as the one in `c15t.config.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**
+
+Add the configuration to `scripts` in `c15t.config.ts`, next to
+`next.config.ts`:
+
+```ts title="c15t.config.ts"
+import { defineConsentConfig } from 'c15t/next';
+import { scripts } from './src/consent-scripts';
+
+export default defineConsentConfig({ scripts });
+```
+
+Keep the rest of your config, such as `mode` and `routePrefix`, in the
+same call. `ConsentRoot` reads the config in the browser, so the layout
+keeps passing only `state`. App Router, Pages Router and static export all
+read the same file. See
+[Next.js scripts and embeds](https://c15t.com/docs/frameworks/next/scripts).
+
+**TanStack Start**
+
+Import the configuration into your root route and pass it to the existing
+`ConsentRoot` as a top-level prop. Keep the loader 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} 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](https://c15t.com/docs/frameworks/tanstack-start/scripts).
+
+**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 `manifest()` value from the
+[React quickstart](../frameworks/react/quickstart.md). 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](https://c15t.com/docs/frameworks/nuxt/scripts).
+
+**Vue**
+
+Pass the scripts to the existing `c15tVue` plugin call in `src/main.ts`:
+
+```ts title="src/main.ts"
+import { c15tVue, manifest } from 'c15t/vue/vue-plugin';
+import { scripts } from './consent-scripts';
+
+app.use(c15tVue, {
+  mode: manifest(),
+  scripts,
+});
+```
+
+Keep your existing `mode` 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](https://c15t.com/docs/frameworks/vue/scripts).
+
+**Astro**
+
+Add the scripts to the client entrypoint from the
+[Astro quickstart](https://c15t.com/docs/frameworks/astro/quickstart), `src/c15t.client.ts`,
+which the integration finds on its own. Keep `astro.config.mjs` as it is.
+If the module already exports scripts, combine the two arrays.
+
+```ts title="src/c15t.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 { ConsentProvider, manifest } from 'c15t/svelte';
+  import { scripts } from './consent-scripts';
+</script>
+
+<ConsentProvider mode={manifest()} {scripts}>
+  <!-- Keep your application, consent UI and preferences link here. -->
+</ConsentProvider>
+```
+
+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 `ConsentRoot` in the root layout. Keep the
+handle and the layout load from the [SvelteKit quickstart](https://c15t.com/docs/frameworks/sveltekit/quickstart).
+
+```svelte title="src/routes/+layout.svelte"
+<script lang="ts">
+  import { ConsentRoot } from 'c15t/svelte';
+  import { scripts } from '../consent-scripts';
+
+  let { children, data } = $props();
+</script>
+
+<ConsentRoot state={data.consent} {scripts}>
+  {@render children()}
+  <!-- Keep your consent UI and preferences link here. -->
+</ConsentRoot>
+```
+
+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](https://c15t.com/docs/frameworks/html/scripts).
+
+**JavaScript**
+
+Pass the scripts to `init()` from `@c15t/browser`, next to your mode:
+
+```ts
+import { init, manifest } from '@c15t/browser';
+import { scripts } from './consent-scripts';
+
+const consent = init({
+  mode: manifest(),
+  scripts,
+});
+```
+
+Keep the mode 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](https://c15t.com/docs/frameworks/javascript/scripts).
+
+## Options
+
+| Option        | Default                                                        | Behavior                                                                                                                                             |
+| ------------- | -------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `writeKey`    | Required                                                       | Write key of your Data Pipelines JavaScript source. Whitespace is trimmed. If it's missing or blank, c15t logs an error and never loads Customer.io. |
+| `region`      | `us`                                                           | `us` uses `cdp.customer.io`. `eu` uses `cdp-eu.customer.io`. Any other value throws `customerIo: region must be 'us' or 'eu'`.                       |
+| `loadOptions` | Unset                                                          | Options for the Customer.io loader, such as destination settings. The helper always sets `initialPageview` to `false`, even if you pass `true`.      |
+| `category`    | `marketing`                                                    | Consent condition for the whole loader.                                                                                                              |
+| `cdnUrl`      | Region's HTTPS origin                                          | Origin for the loader, source settings and SDK files. See [Use a proxy](#use-a-proxy). Blank values use the regional default.                        |
+| `scriptUrl`   | `<cdnUrl>/v1/analytics-js/snippet/<writeKey>/analytics.min.js` | Overrides only the initial loader URL. Blank values use the default.                                                                                 |
+
+## Use a proxy
+
+Set `cdnUrl` to your proxy's HTTP(S) origin. The helper trims whitespace and
+trailing slashes. Any path, query, fragment or credentials, or a value without
+a scheme, throws `customerIo: cdnUrl must be an HTTP(S) origin`. `cdnUrl` sets
+`cioanalytics._cdn` as well as the default loader URL, so source settings and
+SDK files come from your proxy too. The proxy must keep Customer.io's paths and
+forward to the source's regional host. A `scriptUrl` override alone doesn't
+change where the SDK loads its files from.
+
+`cdnUrl` doesn't move collected events. To proxy Data Pipelines events, set
+`apiHost` for the `Customer.io Data Pipelines` integration in `loadOptions` to
+your collection proxy host plus `/v1`, without a scheme, and set `protocol` to
+`https`:
+
+```ts title="src/customer-io-proxy.ts"
+import { customerIo } from '@c15t/integrations/customer-io';
+
+export const proxiedScripts = [
+	customerIo({
+		cdnUrl: 'https://analytics.example.com',
+		loadOptions: {
+			integrations: {
+				'Customer.io Data Pipelines': {
+					apiHost: 'collect.example.com/v1',
+					protocol: 'https',
+				},
+			},
+		},
+		writeKey: 'YOUR_WRITE_KEY',
+	}),
+];
+```
+
+Replace both example domains with your own proxies. Neither option redirects
+traffic that destinations send themselves. Configure each destination
+separately where it supports a proxy.
+
+## Loading and revocation
+
+After consent, the helper creates Customer.io's array queue and method stubs,
+sets `_writeKey`, `_cdn` and `_loadOptions`, and loads the SDK. The script
+element carries the namespace attribute Customer.io requires. If the page
+already has a loaded `cioanalytics`, the helper keeps it.
+
+The helper sends the first `page()` call itself, once the SDK has loaded and
+consent is still granted, and again on each new grant after that. That's why
+it forces `initialPageview` to `false`. It copies `loadOptions`, so your object
+stays unchanged. It doesn't wait for `ready()`, because a destination can fail
+to initialize and some destinations need `page()` before they can start. A
+revoked or disposed loader doesn't send a pending first page view.
+
+While the SDK downloads, each method stub returns the same `cioanalytics`
+queue. Calls such as `cioanalytics.identify('customer-123').track('Signed up')`
+queue both calls in order. `cioanalytics` is undefined before consent, so
+check marketing consent before your own code calls it.
+
+On withdrawal, the helper calls `reset()` to clear identity. That doesn't stop
+the SDK, its retries or destination SDKs from sending, so keep
+`reloadOnConsentRevoked` enabled. The SDK loads once per page. A new grant on
+the same page reuses it instead of adding another copy. On the next page,
+while marketing is denied, the helper creates no queue and makes no vendor
+requests.
+
+## Cookies and storage
+
+Customer.io can use analytics identity cookies and `localStorage` keys
+including `ack`, `reclaimStart`, `reclaimEnd`, `inProgress` and `queue`.
+Destinations can add storage of their own. `reset()` doesn't erase all
+destination data.
+
+## Verify Customer.io
+
+Filter the Network panel by `customer.io`, or by your proxy's domain. Before
+consent, and after you allow an unrelated category, check that there is no
+snippet request, no `cioanalytics` global and no vendor cookies or browser
+storage. Allow marketing and check that the SDK initialized. Withdraw marketing
+and confirm the page reloads and the next page stays quiet. A 200 JSON response
+for an invalid write key doesn't prove the SDK initialized.
+
+With a proxy, check that the snippet, `/v1/projects/<writeKey>/settings` and
+the SDK files come from the CDN proxy. Check event collection separately
+against the `apiHost` you set. A successful load doesn't prove that events
+reach your workspace or destinations.
+
+Sources: Customer.io's [JavaScript source](https://docs.customer.io/cdp/sources/connections/javascript/js-source/),
+[in-app snippet](https://docs.customer.io/integrations/data-in/connections/javascript/in-app/),
+[proxy setup](https://docs.customer.io/integrations/data-in/connections/javascript/js-source-proxy/)
+and [utility methods](https://docs.customer.io/integrations/data-in/connections/javascript/utility-methods/).
+
+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 lists its vendor by name in the preference dialog, so 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/databuddy.md

@@ -1,30 +1,29 @@
 ---
 title: Databuddy
-description: Load the Databuddy SDK on every page with the c15t databuddy
-  helper, switch its disabled flag and config from measurement consent, and
-  check both in DevTools.
+description: Load Databuddy only after measurement consent with the c15t
+  databuddy helper, turn off tracking features you do not use, record sessions
+  with the replay option, and check revocation in DevTools.
 seoTitle: Databuddy cookie consent with c15t
-seoDescription: Keep Databuddy disabled without measurement consent, and turn it
-  on with consent. Set it up with the c15t databuddy helper.
+seoDescription: Load Databuddy and its session replay only with measurement
+  consent, and stop both when consent is withdrawn. Set it up with the c15t
+  databuddy helper.
 icon: databuddy
 group: integrations
 ---
 
-The c15t `databuddy` helper loads `databuddy.js` on every page, before the
-visitor chooses. The helper uses `alwaysLoad`, but its category is
-`measurement`. While `measurement` has no consent, the helper sets
-`window.databuddy.options.disabled` to `true`. It also sets
-`window.databuddyConfig` to `configWhenDenied`, unless your page set
-`window.databuddyConfig` first. When `measurement` has consent, the helper
-changes to `configWhenGranted` and sets `disabled` to `false`. If the visitor
-withdraws consent, the helper changes both values back.
+The c15t `databuddy` helper waits for `measurement` consent before it loads
+`databuddy.js`. Before the visitor allows measurement, the page sends no
+request to Databuddy and Databuddy stores nothing. If the visitor withdraws
+consent, the helper disables the Databuddy tracker and stops session replay,
+and c15t reloads the page.
 
 ## Configure Databuddy
 
 Copy the client ID from your Databuddy project. The helper passes it to the
-script as `data-client-id`. Remove any existing Databuddy script and any code
-that sets `window.databuddyConfig`. The helper seeds that global only when it
-is absent, so an existing value overrides your initial state.
+script as `data-client-id`. Remove any existing Databuddy or `replay.js` script
+tag, any `<Databuddy />` component from `@databuddy/sdk`, and any code that
+sets `window.databuddyConfig`. The helper seeds that global only when it is absent,
+so an existing value overrides it.
 
 | Package manager | Command                          |
 | :-------------- | :------------------------------- |
@@ -37,11 +36,7 @@ is absent, so an existing value overrides your initial state.
 import { databuddy } from '@c15t/integrations/databuddy';
 
 export const scripts = [
-	databuddy({
-		clientId: 'YOUR_CLIENT_ID',
-		configWhenGranted: { disabled: false },
-		configWhenDenied: { disabled: true },
-	}),
+	databuddy({ clientId: 'YOUR_CLIENT_ID', features: { interactions: false } }),
 ];
 ```
 
@@ -176,7 +171,7 @@ pass them as a top-level prop:
 
 ```svelte title="src/App.svelte"
 <script lang="ts">
-  import { ConsentProvider, manifest } from '@c15t/svelte';
+  import { ConsentProvider, manifest } from 'c15t/svelte';
   import { scripts } from './consent-scripts';
 </script>
 
@@ -195,7 +190,7 @@ handle and the layout load from the [SvelteKit quickstart](https://c15t.com/docs
 
 ```svelte title="src/routes/+layout.svelte"
 <script lang="ts">
-  import { ConsentRoot } from '@c15t/svelte';
+  import { ConsentRoot } from 'c15t/svelte';
   import { scripts } from '../consent-scripts';
 
   let { children, data } = $props();
@@ -251,43 +246,123 @@ A kernel you create yourself needs a loader from
 
 ## Options
 
-| Option              | Default                                 | Behavior                                                                                                                 |
-| ------------------- | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
-| `clientId`          | Required                                | Set as `data-client-id`. The helper trims it. Empty or whitespace-only values log an error and the script does not load. |
-| `configWhenGranted` | Required                                | Object set as `window.databuddyConfig` while measurement is allowed.                                                     |
-| `configWhenDenied`  | Required                                | Object set as `window.databuddyConfig` while measurement is denied.                                                      |
-| `apiUrl`            | `https://basket.databuddy.cc`           | Collection endpoint, set as `data-api-url`.                                                                              |
-| `scriptUrl`         | `https://cdn.databuddy.cc/databuddy.js` | Loader URL override. A blank value falls back to the default.                                                            |
+| Option                   | Default                                 | Behavior                                                                                                                                                                                       |
+| ------------------------ | --------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `clientId`               | Required                                | Set as `data-client-id`. The helper trims it. Empty or whitespace-only values log an error and the script does not load.                                                                       |
+| `loadMode`               | `'after-consent'`                       | When the script loads. See [loading and revocation](#loading-and-revocation).                                                                                                                  |
+| `features.interactions`  | Unset, Databuddy turns it on            | Sets `data-track-interactions`.                                                                                                                                                                |
+| `features.webVitals`     | Unset, Databuddy turns it off           | Sets `data-track-web-vitals`.                                                                                                                                                                  |
+| `features.errors`        | Unset, Databuddy turns it off           | Sets `data-track-errors`.                                                                                                                                                                      |
+| `features.outgoingLinks` | Unset, Databuddy turns it off           | Sets `data-track-outgoing-links`.                                                                                                                                                              |
+| `replay`                 | `false`                                 | `true` or an object loads `replay.js` while measurement is allowed. See [record sessions](#record-sessions).                                                                                   |
+| `replay.maskText`        | Unset, Databuddy masks text             | Sets `data-mask-text` on `replay.js`. `false` records page text.                                                                                                                               |
+| `replay.recordIframes`   | Unset, Databuddy turns it off           | Sets `data-record-iframes` on `replay.js`.                                                                                                                                                     |
+| `replay.scriptUrl`       | `https://cdn.databuddy.cc/replay.js`    | Replay script URL override. A blank value falls back to the default.                                                                                                                           |
+| `configWhenGranted`      | `{ apiUrl, clientId, disabled: false }` | Object set as `window.databuddyConfig` before the script loads with measurement allowed, and on each grant. c15t sets its `disabled` key from consent.                                         |
+| `configWhenDenied`       | `{ apiUrl, clientId, disabled: true }`  | With `loadMode: 'always'` only. Object set as `window.databuddyConfig` before the script loads without measurement permission, and on each refusal. c15t sets its `disabled` key from consent. |
+| `apiUrl`                 | `https://basket.databuddy.cc`           | Collection endpoint, set as `data-api-url`.                                                                                                                                                    |
+| `scriptUrl`              | `https://cdn.databuddy.cc/databuddy.js` | Loader URL override. A blank value falls back to the default.                                                                                                                                  |
+
+## Turn off features you do not use
+
+Databuddy collects some data unless the site turns it off. Set a `features`
+switch to `false` to stop that collection, or to `true` to turn on a feature
+Databuddy leaves off:
+
+```ts
+databuddy({
+	clientId: 'YOUR_CLIENT_ID',
+	features: {
+		interactions: false,
+		webVitals: false,
+		errors: false,
+		outgoingLinks: false,
+	},
+});
+```
+
+| Switch          | Databuddy default | What Databuddy collects                      |
+| --------------- | ----------------- | -------------------------------------------- |
+| `interactions`  | On                | Rage clicks, dead clicks and abandoned forms |
+| `webVitals`     | Off               | FCP, LCP, INP, CLS, TTFB and FPS             |
+| `errors`        | Off               | JavaScript errors, with message and stack    |
+| `outgoingLinks` | Off               | Clicks on links to other sites               |
+
+Each switch sets a `data-track-*` attribute on the script. An unset switch
+sets no attribute, so Databuddy keeps its own default. Databuddy reads `data-*`
+attributes after `window.databuddyConfig`, so a switch wins over the same key
+in `configWhenGranted` or `configWhenDenied`.
 
 ## Loading and revocation
 
-`databuddy` uses the `measurement` category with `alwaysLoad`, so the
-Databuddy script loads on every page, before the visitor chooses. Before the
-script loads, the helper sets `window.databuddyConfig` to `configWhenDenied` or
-`configWhenGranted`, unless that global already exists. After the script
-loads, the helper sets `window.databuddy.options.disabled` to `true` without
-measurement permission and to `false` with it. On each later consent change,
-the helper replaces `window.databuddyConfig` with the matching object and
-updates `disabled` again. c15t never removes the script.
+| `loadMode`        | When `databuddy.js` loads         | Before the visitor allows measurement                                      |
+| ----------------- | --------------------------------- | -------------------------------------------------------------------------- |
+| `'after-consent'` | Only while measurement is allowed | No request to Databuddy and no storage                                     |
+| `'always'`        | On every page, before consent     | The script loads and stores a visitor ID while `disabled` stops it sending |
+
+On revocation, the helper sets `window.databuddy.options.disabled` to `true`,
+which stops the main tracker sending. It also sets `disabled: true` in
+`window.databuddyConfig`, or replaces the object with `configWhenDenied` in
+`'always'` mode. A `databuddy.js` download that finishes after the refusal then
+starts disabled. With [`replay`](#record-sessions) on, the helper also stops
+the recorder. c15t then reloads the page, which is the default
+`reloadOnConsentRevoked` behavior. On a later grant, c15t sets both back to
+`false`, and `window.databuddyConfig` to `configWhenGranted`.
+
+With `loadMode: 'always'`, `databuddy.js` runs before the visitor chooses. It
+stores its visitor ID in localStorage even while `disabled` is `true`.
+Databuddy's own consent guidance is to delay loading until consent where prior
+consent is required. Use `'always'` only where your policy allows that.
+
+## Record sessions
+
+Databuddy records sessions with a separate script, `replay.js`. Set `replay`
+to have the helper load it:
+
+```ts
+databuddy({ clientId: 'YOUR_CLIENT_ID', replay: true });
+```
 
-The Databuddy SDK decides what `disabled` stops. The helper cannot prevent the
-script request before consent. If Databuddy must receive no request before
-consent, write a
-[custom gated integration](./building-integrations.md) instead.
+`replay: true` keeps Databuddy's replay defaults, which mask page text and
+typed input. The helper adds `replay.js` only while measurement is allowed,
+including with `loadMode: 'always'`, and passes it the same `clientId` and
+`apiUrl` as `databuddy.js`. `replay.js` does not read Databuddy's `disabled`
+flag, so the helper calls `window.databuddyReplay.stop()` and removes the
+script on revocation. It does the same when you turn `replay` off, remove the
+helper or dispose the script loader. Recording stops without waiting for the
+page reload. A later grant loads `replay.js` again.
+
+`replay: { maskText: false }` records page text; typed input stays masked. Use
+it only when your pages show no personal data, such as names, email addresses
+or order details. Recordings would otherwise include that data. To change
+masking for one element, add an attribute to it in your markup:
+
+* `data-replay-unmask` records the text of an element that is safe to show.
+* `data-replay-block` leaves the element out. The recording shows an empty box
+  of the same size.
+
+`recordIframes: true` records your own embedded pages into the parent page's
+recording. Set it on the framed page too. See
+[Databuddy's session replay guide](https://www.databuddy.cc/docs/session-replay)
+for its limits and the dashboard setting that turns replay off.
+
+Do not also add `replay.js` to the page as a plain `<script>` tag. Outside
+c15t, it starts recording on the visitor's first click, scroll or key press,
+and uploads that recording even if the visitor has not chosen.
 
 ## Verify Databuddy
 
-1. In a private window with an opt-in policy, load the page. `databuddy.js`
-   loads from `cdn.databuddy.cc` with your `data-client-id`. In the console,
-   `window.databuddyConfig` matches `configWhenDenied` and
-   `window.databuddy.options.disabled` is `true`.
-2. Click Reject, then reload. `disabled` is still `true`, and DevTools Network
-   shows no event request to your `apiUrl`.
-3. Open Privacy settings and allow measurement. Without a reload, `disabled`
-   becomes `false`, `window.databuddyConfig` matches `configWhenGranted`, and
-   event requests reach your `apiUrl`.
+1. In a private window with an opt-in policy, load the page. DevTools Network
+   shows no request to `cdn.databuddy.cc` or `basket.databuddy.cc`, and
+   Application shows no `did` key in localStorage.
+2. Click Reject, then reload. There are still no Databuddy requests.
+3. Open Privacy settings and allow measurement. Without a reload,
+   `databuddy.js` loads from `cdn.databuddy.cc` with your `data-client-id`, and
+   requests reach your `apiUrl`. With `replay` on, `replay.js` loads too. Move
+   the pointer or scroll, and a `POST` to `/replay` follows within a few
+   seconds.
 4. Turn measurement off again and save. c15t reloads the page, and the new
-   page starts with `disabled` set to `true`.
+   page sends no request to `cdn.databuddy.cc` or `basket.databuddy.cc`.
 
 See the [consent verification guide](../guides/verify-consent.md) for
 navigation and hosting checks.