@c15t/react 3.2.0-canary.0 → 3.2.1

package/docs/integrations/ada.md

@@ -0,0 +1,396 @@
+---
+title: Ada
+description: Load Ada Messaging after functionality consent with the c15t ada
+  helper, configure regional Agents, and stop the widget when consent is
+  revoked.
+seoTitle: Ada Messaging cookie consent with c15t
+seoDescription: Gate Ada Messaging on functionality consent with c15t. Keep the
+  SDK interface private, stop the widget on revocation, and verify its requests
+  and storage.
+icon: bot
+group: integrations
+---
+
+Ada Messaging adds an Ada AI Agent chat widget to your site. The c15t `ada`
+helper waits for `functionality` consent before it imports Ada's Messaging Web
+SDK, and it keeps the Messaging interface private.
+
+When the visitor withdraws, the helper calls Ada's `stop()` to remove the
+widget, and c15t reloads the page by default. `stop()` doesn't delete stored
+conversations or cookies.
+
+## Configure Ada Messaging
+
+Get your AI Agent's public `handle` from your Ada team. Most installations
+need only the handle. Set `cluster` or `domain` only when Ada gives you a
+regional configuration.
+
+Remove any existing Ada module snippet, `embed2.js` script tag, or tag-manager
+installation. A separate Ada installation can load before c15t grants consent,
+and Ada allows only one Messaging interface per page.
+
+| 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 { ada } from '@c15t/integrations/ada';
+
+export const scripts = [ada({ handle: 'YOUR_ADA_HANDLE' })];
+```
+
+## 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).
+
+This helper targets the Messaging Web SDK. It doesn't load the legacy Chat SDK
+and has no `legacy` option.
+
+## Options
+
+| Option    | Default              | Behavior                                                                                                                                                                 |
+| --------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `handle`  | Required             | Public AI Agent handle passed to `start()`. Surrounding whitespace is trimmed. If it's missing or blank, c15t logs `ada: missing or invalid handle` and never loads Ada. |
+| `cluster` | Ada's default region | Regional segment, such as `eu`, `us2` or `maple`, or a full cluster domain supplied by Ada. Trimmed. Blank values are omitted.                                           |
+| `domain`  | Ada's default domain | Ada base-domain segment. Use only the value Ada gives you. Trimmed. Blank values are omitted.                                                                            |
+
+The helper imports `https://messaging-assets.ada.support/sdk.js`. You can't
+set a custom SDK URL, and the helper doesn't bundle the runtime into your app.
+Ada's entry module imports the current runtime from its CDN.
+
+If your site has a Content Security Policy, allow
+`https://messaging-assets.ada.support` in `script-src`, `connect-src` and
+`frame-src`. Also allow your Agent's API origin in `connect-src`. Follow
+[Ada's CSP instructions](https://docs.ada.cx/messaging/web/getting-started#content-security-policy)
+for the origin that matches your handle and region.
+
+## Loading and revocation
+
+The helper returns a callback-only c15t script with no `src`. When its consent
+is granted, it imports the SDK, calls the module's `createAdaEmbedInterface()`
+export, and awaits `start({ handle, cluster, domain })`. It creates no
+`window.adaEmbed` or `window.adaSettings` global. Repeated consent updates don't
+start a second widget.
+
+The helper checks the permission c15t passes to it, so if you change the
+script's category, the gate changes too. The visitor's Ada vendor switch
+applies inside an allowed category.
+
+### One configuration per page
+
+Keep one Ada helper in your scripts array. Helpers with the same handle,
+cluster and domain share one private interface, and Messaging stops when the
+last of them is revoked or disposed.
+
+A helper with different settings doesn't change the running widget. When it
+gets consent while another configuration is active, it logs a `console.warn`
+(`ada: Ada supports one configuration per page`) and does nothing until the
+page reloads. It stays ignored even after the first configuration stops.
+
+### Stopping the widget
+
+When the last granted registration loses consent or is disposed, the helper
+calls `stop()`. Ada documents that `stop()` removes the SDK frames and
+interrupts a pending `start()`. A later grant waits for the earlier start and
+stop to finish, then starts the same interface again. Once every registration
+is gone and `stop()` has run, a new registration can start it with different
+settings.
+
+If consent is withdrawn while the SDK import is still pending, the helper
+doesn't create or start the interface when the import finishes. Browsers can't
+cancel a dynamic import that has already begun, so the SDK can still fetch its
+dependencies and write its own bootstrap storage. Keep `reloadOnConsentRevoked`
+enabled to end that work. Imported code stays in memory until the page unloads.
+
+Ada has no documented consent signal or opt-out action. `stop()` doesn't
+promise to erase conversation history, stored tokens or cookies. The helper
+doesn't call `deleteHistory()`, which permanently deletes the conversation and
+resets the session.
+
+### Errors
+
+The helper logs failures with `console.error` and doesn't throw:
+
+* If the import fails, the module has no `createAdaEmbedInterface` export, or
+  `start()` rejects, it logs `ada: failed to start Messaging.` and drops the
+  current registrations. The next consent update can try again, or another
+  configuration can start instead.
+* If `stop()` rejects, it logs `ada: failed to stop Messaging.`
+
+## Cookies and storage
+
+[Ada's client-side storage list](https://static.ada.support/ada-web-storage-list.html)
+covers several SDK generations and optional integrations. Entries include:
+
+| Name                                                     | Purpose and retention                                                                                                           |
+| -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
+| `__Host-ada-session-[session ID]-[generation]`           | Server-set HttpOnly refresh credential on the Agent's Ada subdomain. Ada lists a session duration of up to seven days.          |
+| `ada-embed_*`, `ada-embed-*`, `ada-functional-storage`   | SDK state, session values and version caches. Ada lists these as persistent Web Storage.                                        |
+| `chatter`, `created`, `inLiveChat`, `messagingAuthState` | Conversation, session, handoff and authentication state. Ada lists persistent Web Storage, including entries on the Ada domain. |
+
+The hosted SDK bootstrap also stores rollout assignments under
+`ada-messaging-sdk-rollout:*` in the host page's local storage. This happens
+while the module evaluates, which is why c15t gates the import itself.
+Rollout assignments can remain after `stop()`.
+
+Your Agent can embed other services, such as Calendly, YouTube or a live
+support platform. Their storage depends on your configuration, so inspect the
+widget's frames as well as the host page. JavaScript on your page can't read
+or clear Ada's HttpOnly cookies on another origin.
+
+## Verify Ada Messaging
+
+Use a private window with an opt-in policy and your real Ada handle. In
+DevTools, disable the Network cache and filter by `ada.support`:
+
+1. Load the page without granting functionality. No Ada module, manifest,
+   iframe or API request appears, and the fresh browser context has no Ada
+   storage.
+2. Reject optional consent and reload. Ada still makes no request.
+3. Allow functionality. Look for `sdk.js`, the rollout manifest, the versioned
+   SDK module and the Ada launcher. `window.adaEmbed` stays undefined.
+4. Revoke functionality or turn off the Ada vendor switch. The helper calls
+   `stop()`, and c15t reloads by default. The new page makes no Ada request.
+   Stored conversation data can remain.
+5. Allow functionality again. The widget starts once. Repeat the grant and
+   revoke steps on a throttled network to check a pending startup.
+
+Check the console too. An `ada:` warning means a second configuration with
+different settings is in your scripts array.
+
+The helper already calls `stop()`, the opt-out step the shared checklist below
+asks for. Keep the reload enabled anyway, for an import that's still pending.
+
+Sources: [Messaging Web SDK installation](https://docs.ada.cx/messaging/web/getting-started#embed-with-a-module-script),
+[settings and lifecycle actions](https://docs.ada.cx/messaging/web/sdk-api-reference),
+[keep the Messaging interface private](https://docs.ada.cx/messaging/web/security-best-practices#keep-the-client-in-a-private-scope),
+and [Ada's client-side storage list](https://static.ada.support/ada-web-storage-list.html).
+
+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.