@c15t/react 3.1.0 → 3.2.0

package/docs/integrations/dynamic-yield.md

@@ -0,0 +1,373 @@
+---
+title: Dynamic Yield
+description: Load Dynamic Yield personalization scripts after experience
+  consent, set the page context and synchronize Active Cookie Consent with c15t.
+seoTitle: Dynamic Yield cookie consent with c15t
+seoDescription: Gate both Dynamic Yield scripts on experience consent, select a
+  US or EU section, and send Active Cookie Consent updates with c15t.
+icon: sparkles
+group: integrations
+---
+
+The c15t `dynamicYield` helper loads Dynamic Yield after `experience` consent.
+It sets `DY.userActiveConsent` before loading `api_dynamic.js`, then loads
+`api_static.js` after the first script finishes. No Dynamic Yield global,
+preconnect, loader request or storage is created before the helper's consent
+gate opens.
+
+Dynamic Yield recommends synchronous scripts directly in the page's `<head>`
+to avoid flicker. Waiting for consent and loading the scripts in sequence
+changes that timing, so visitors can see the original page before a campaign
+applies. Check your campaigns and page rendering with Dynamic Yield before
+using this helper for experiments that need to run before paint.
+
+## Configure Dynamic Yield
+
+Copy the section ID and data center from your section's
+[installation snippet](https://dy.dev/docs/implement-script). Enable
+[Active Cookie Consent](https://dy.dev/docs/active-cookie-consent) with Dynamic
+Yield Support. Preview mode lets you check it first. Dynamic Yield ignores the
+consent API until this setting is enabled for your section.
+
+Remove existing Dynamic Yield snippets, tag-manager tags and preconnects.
+c15t gates only the scripts registered with it.
+
+| 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 { dynamicYield } from '@c15t/integrations/dynamic-yield';
+
+export const scripts = [
+	dynamicYield({
+		recommendationContext: { lng: 'en_GB', type: 'HOMEPAGE' },
+		region: 'eu',
+		sectionId: 'YOUR_SECTION_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 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                                                                                                                       |
+| ----------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------ |
+| `sectionId`             | Required       | Public section ID. Trimmed and URL-encoded as one path segment. Missing or blank values log an error and skip the integration. |
+| `region`                | `'us'`         | `'us'` uses `cdn.dynamicyield.com`; `'eu'` uses `cdn-eu.dynamicyield.com`. Match the section's data center.                    |
+| `recommendationContext` | Not set        | Page context assigned before either loader runs. Omit to preserve a context your app already set.                              |
+| `category`              | `'experience'` | c15t consent category or condition that gates both loaders and the consent signal.                                             |
+| `nonce`                 | None           | CSP nonce for both loaders. A nonce supplied by your consent provider is forwarded to the second loader too.                   |
+
+`recommendationContext.type` accepts `HOMEPAGE`, `CATEGORY`, `PRODUCT`, `CART`,
+`POST` and `OTHER`. `data` contains the category hierarchy, product SKUs, post ID
+or page identifier. `lng` selects a feed locale such as `en_GB`. Match values
+to the section's product or content feed. See Dynamic Yield's
+[page context guide](https://dy.dev/docs/page-context).
+
+The helper seeds the initial context. Your application owns context updates
+on client-side navigation. Follow Dynamic Yield's
+[context implementation guide](https://dy.dev/docs/code-context) and check
+consent before making your own Dynamic Yield calls.
+
+## Loading and revocation
+
+Before consent, neither loader runs and `window.DY` stays absent unless another
+part of your app created it. Granting the mapped consent creates `DY` if
+needed, sets `DY.userActiveConsent = { accepted: true }`, and starts the
+dynamic loader. The static loader starts after the dynamic loader finishes.
+
+Equivalent helper options reuse the same scripts across framework renders.
+Registrations that share the dynamic loader also share its static loader.
+Sharing is scoped to the same section ID and region; different sections or
+regions request their own loader URLs. Dynamic Yield's consent and page
+context still use the page-global `window.DY`, so configure one section and
+region per page.
+
+The consent signal is page-global too. It stays granted while any Dynamic
+Yield registration has consent, including registrations with different
+sections or regions. Revoking or removing one registration keeps both loader
+elements while another granted registration uses the same URLs. When a
+section's last granted registration is revoked or removed, the helper removes
+its loader elements. When no registration on the page has consent, it sets
+`DY.userActiveConsent = { accepted: false }`.
+
+If consent is withdrawn while the dynamic loader is downloading, the helper
+skips the static loader. Granting consent again starts a new loader sequence.
+
+The SDK's consent setter applies only when Active Cookie Consent is enabled
+for the section. It changes data collection and personalization behavior. It
+does not unload the SDK or guarantee zero requests from code that already
+ran. Keep c15t's default `reloadOnConsentRevoked` behavior enabled.
+
+Dynamic Yield's denied mode can serve limited experiences. This helper waits
+for consent before loading either script, so it does not use denied-mode
+campaign delivery before consent. There is no `alwaysLoad` option.
+
+## Cookies and storage
+
+Dynamic Yield's [cookie and storage inventory](https://dy.dev/docs/cookie-management)
+includes these cookies. Your section and campaigns determine which appear.
+
+| Cookie                 | Documented lifetime |
+| ---------------------- | ------------------- |
+| `_dyid`                | 30 days             |
+| `_dyjsession`          | Browser session     |
+| `_dy_soct`             | 1 year              |
+| `dy_fs_page`           | Browser session     |
+| `_dy_cs_storage_items` | 30 days             |
+| `_dy_cs_cookie_items`  | 30 days             |
+
+Dynamic Yield caps cookie storage at 365 days. Its browser storage also
+includes `_dyuss_`, `_dy_tsrc`, `_dyaud_nchc`, `_dyaud_page`, `_dy_device`,
+`_dycst`, `_dy_csc`, `_dyrc`, `_dybatch`, `_dy_cs_session_items` and
+`_dy_cs_local_items`. `_dyaud_sess` uses session storage. Check the vendor
+inventory and your browser for the keys used by your section.
+
+The helper does not delete previously stored cookies or browser storage.
+Configure cleanup for your deployment and verify it after withdrawal.
+
+## Verify Dynamic Yield
+
+Filter DevTools Network by `dynamicyield.com`. Grant `experience` and check
+that `api_dynamic.js` finishes before the helper appends `api_static.js`.
+Inspect `DY.userActiveConsent.accepted` and your page context. Revoke consent
+and check the next page makes no Dynamic Yield request. Test vendor-specific
+switches and the category override if your app uses them.
+
+Sources: [Implement the Dynamic Yield script](https://dy.dev/docs/implement-script),
+[Active Cookie Consent API](https://dy.dev/docs/active-cookie-consent),
+[Active Cookie Consent mode and limited experiences](https://support.dynamicyield.com/hc/en-us/articles/360014728858-Active-Cookie-Consent-Mode-for-User-Data-Privacy-Management),
+and [cookies and local storage](https://dy.dev/docs/cookie-management).
+
+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/fathom-analytics.md

@@ -166,7 +166,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>
 
@@ -185,7 +185,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();

package/docs/integrations/front-chat.md

@@ -166,7 +166,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>
 
@@ -185,7 +185,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();