@c15t/react 3.1.0 → 3.2.0

package/docs/integrations/gorgias.md

@@ -0,0 +1,365 @@
+---
+title: Gorgias Chat
+description: Load Gorgias Chat after functionality consent, disable its Segment
+  analytics when measurement is denied, and verify loading and revocation with
+  c15t.
+seoTitle: Gorgias Chat cookie consent with c15t
+seoDescription: Load Gorgias Chat with functionality consent. Disable Segment
+  tracking when measurement is denied and use a page reload to stop the running
+  widget.
+icon: messages-square
+group: integrations
+---
+
+Gorgias Chat adds the Gorgias support chat widget to your store or site. The
+c15t `gorgiasChat` helper waits for `functionality` consent before it adds the
+Gorgias loader. When the widget is ready, the helper turns off its Segment
+analytics unless `measurement` is also allowed.
+
+Gorgias has no shutdown API, so the helper can't stop a running widget. By
+default c15t reloads the page on withdrawal, and the reload stops it.
+
+## Configure Gorgias Chat
+
+Copy the public app key from the v3 installation snippet in your Gorgias Chat
+settings. The key is the last part of
+`https://config.gorgias.chat/bundle-loader/YOUR_APP_KEY`. A v2 snippet uses an
+`applicationId` instead. Pass that value as `appKey` with `version: 2`.
+
+Remove any existing Gorgias snippet or automatic installation from your theme,
+tag manager or store app. An installation outside c15t can load Gorgias before
+consent, and the Gorgias loader skips duplicate installations.
+
+| 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 { gorgiasChat } from '@c15t/integrations/gorgias';
+
+export const scripts = [gorgiasChat({ appKey: 'YOUR_GORGIAS_APP_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                                                                                                                                                                                                                     |
+| --------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `appKey`  | Required | Public v3 app key from the installation snippet, or the v2 `applicationId` with `version: 2`. Trimmed and URL-encoded. If it's missing or blank, c15t logs `gorgiasChat: missing or invalid appKey` and never loads Gorgias. |
+| `version` | `3`      | Installation snippet version, `2` or `3`. Version 3 loads `https://config.gorgias.chat/bundle-loader/<appKey>`. Version 2 loads `https://config.gorgias.chat/gorgias-chat-bundle-loader.js?applicationId=<appKey>`.          |
+
+## Loading and revocation
+
+Until its consent gate allows Gorgias, the helper adds no vendor script,
+creates no vendor global and writes no vendor cookies or storage. The default
+category is `functionality`. If you map the script to another category, that
+category and the visitor's Gorgias vendor switch control the loader.
+
+After consent, c15t appends the loader to `<body>`. Gorgias then starts the
+widget asynchronously. The helper listens for `gorgias-widget-loaded` before
+it appends the loader. If `window.GorgiasChat` exists when the loader finishes,
+it also waits for `GorgiasChat.init()` to resolve, whichever comes first. When
+the widget is ready, the helper reads the current measurement choice, not the
+one from when the loader started.
+
+Revocation, disposal or a loader error cancels the helper's pending readiness
+work. It can't cancel Gorgias's own startup once the loader has run. If
+`GorgiasChat.init()` rejects while consent still allows Gorgias, the helper
+logs `gorgiasChat: chat initialization failed.` and stops waiting.
+
+On revocation, c15t removes the loader. If the widget is already ready, the
+helper also calls `disableSegment()`, even when measurement is still allowed.
+Gorgias's `close()` and `hideChat(true)` methods only change the widget's
+visibility. They don't stop its requests or clear its session, and Gorgias
+documents no full shutdown API. Keep `reloadOnConsentRevoked` enabled.
+
+## Measurement consent and Segment
+
+When the widget becomes ready without measurement consent, the helper calls
+`GorgiasChat.disableSegment()` right away. It also calls it if the
+visitor withdraws measurement while the widget stays allowed. This follows
+Gorgias's
+[documented analytics customization](https://docs.gorgias.com/en-US/html-snippets-for-chat-customization-460197).
+
+Gorgias has no call to turn Segment back on. Once it's off, it stays off for
+that page, even if the visitor then allows measurement. After a reload with
+measurement allowed, the new widget uses its default analytics.
+
+`disableSegment()` only works after the widget starts. It doesn't prove that
+the widget sent no analytics request before its ready event. Check the requests
+your own widget and account settings produce.
+
+## Cookies and storage
+
+The Gorgias help pages don't list the widget's cookie names, storage keys or
+lifetimes in full. A Chromium probe of the public Gorgias help-center
+installation found the `_dd_s` cookie and these localStorage keys after
+functionality consent: `gorgias.ai-agent-state`, `gorgias.version`,
+`gorgias.storage-updated-at` and `gorgias.language-loaded`. They remained
+after revocation. Account API and collection requests were blocked, so this is
+a partial list, not a verified chat session. Names and lifetimes can change by
+version and account.
+
+A reload stops the running widget but doesn't delete cookies or storage that
+Gorgias already created. Record the widget's storage after you grant consent
+and again after you start a conversation, then add your own cleanup rules where
+you need them. Gorgias's
+[chat privacy disclosure](https://docs.gorgias.com/en-US/chat-add-a-privacy-disclosure-361578)
+can describe how you handle chat data. It doesn't replace the consent gate.
+
+## Verify Gorgias Chat
+
+Use your own app key in a private window with an opt-in policy. In DevTools,
+filter Network by `gorgias` and check Application for cookies, localStorage
+and sessionStorage.
+
+1. Before a choice, and after you reject functionality and reload, no Gorgias
+   script or request appears.
+2. Grant functionality. The loader requests your app key, and the widget
+   appears for an active Gorgias installation.
+3. Leave measurement denied and check the widget's Segment requests.
+   `disableSegment()` runs after the widget is ready, so check the first load
+   as well as later interactions.
+4. Revoke functionality. The page reloads, and the new page makes no Gorgias
+   request. Check stored data separately, because the reload doesn't remove it.
+
+A placeholder or deleted app key still returns HTTP 200, with only a warning
+that the installation is incorrect or deleted. That response doesn't prove the
+widget works. Check that the widget appears.
+
+Sources: [customize the chat widget with HTML and JavaScript](https://docs.gorgias.com/en-US/customize-the-chat-widget-with-HTML-and-JavaScript-286032),
+[HTML snippets for chat customization](https://docs.gorgias.com/en-US/html-snippets-for-chat-customization-460197),
+[add a privacy disclosure](https://docs.gorgias.com/en-US/chat-add-a-privacy-disclosure-361578),
+and [Gorgias privacy notice](https://www.gorgias.com/legal/privacy).
+
+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/heap.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/hightouch.md

@@ -164,7 +164,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>
 
@@ -183,7 +183,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/hotjar.md

@@ -10,16 +10,22 @@ icon: hotjar
 group: integrations
 ---
 
-The c15t `hotjar` helper keeps Hotjar off the page until `measurement` has
-consent. Until then, c15t does not define `window._hjSettings` or `window.hj`.
-The helper sends no consent signal to Hotjar. If the visitor withdraws consent,
-c15t removes the loader script element. By default, c15t also reloads the page.
-The reload stops Hotjar.
+Hotjar records what visitors do on your pages, so it should load only when
+consent allows analytics. The c15t `hotjar` helper waits until the
+`measurement` category is allowed before it adds the Hotjar loader. Until then,
+c15t doesn't define `window._hjSettings` or `window.hj`, and it loads nothing
+from Hotjar. Under an opt-in policy, that wait lasts until the visitor allows
+analytics.
+
+Withdrawal needs more care. c15t sends Hotjar no consent signal, so it can't
+tell a running recording to stop. By default it reloads the page instead, and
+the reload ends the recording.
 
 ## Configure Hotjar
 
-Copy the site ID from your Hotjar tracking code, where it is the `hjid` value.
-Remove the original tracking code.
+Find your site ID in the Hotjar tracking code. It's the `hjid` value. Then
+delete the tracking code from your app. c15t doesn't control that snippet, so
+if it stays, Hotjar loads and records even after the visitor rejects analytics.
 
 | Package manager | Command                          |
 | :-------------- | :------------------------------- |
@@ -165,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>
 
@@ -184,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();
@@ -240,30 +246,38 @@ A kernel you create yourself needs a loader from
 
 ## Options
 
-| Option      | Default                                                       | Behavior                                                                                                                                                                     |
-| ----------- | ------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `siteId`    | Required                                                      | Site ID as a number or string. Set as `window._hjSettings.hjid` and used in the default loader URL. Missing, empty and `0` values log an error and the script does not load. |
-| `version`   | `6`                                                           | Script version, set as `window._hjSettings.hjsv` and the `sv` query parameter of the default loader URL.                                                                     |
-| `scriptUrl` | `https://static.hotjar.com/c/hotjar-<siteId>.js?sv=<version>` | Loader URL override.                                                                                                                                                         |
+| Option      | Default                                                       | Behavior                                                                                                                                                                      |
+| ----------- | ------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `siteId`    | Required                                                      | Site ID as a number or string. Set as `window._hjSettings.hjid` and used in the default loader URL. If it's missing, empty or `0`, c15t logs an error and never loads Hotjar. |
+| `version`   | `6`                                                           | Script version, set as `window._hjSettings.hjsv` and the `sv` query parameter of the default loader URL.                                                                      |
+| `scriptUrl` | `https://static.hotjar.com/c/hotjar-<siteId>.js?sv=<version>` | Loader URL override.                                                                                                                                                          |
 
 ## Loading and revocation
 
-`hotjar` uses the `measurement` category. When measurement becomes allowed,
-the helper sets `window._hjSettings` and a queue-backed `window.hj` stub, each
-only when the global is undefined, then loads the Hotjar loader.
+`hotjar` uses the `measurement` category. When `measurement` is allowed, the
+helper sets `window._hjSettings` and a `window.hj` stub that queues calls, then
+loads the Hotjar script. If your page already defines either global, the helper
+leaves it alone.
 
-On revocation the helper removes the loader script element and calls no Hotjar
-API. A recording in progress continues until the page unloads, so c15t's
-default reload on revocation is what ends it.
+When the visitor withdraws, the helper removes the script element. Hotjar is
+already running by then, so removing the element doesn't stop it. The default
+page reload does. If you set `reloadOnConsentRevoked: false`, Hotjar keeps
+recording until the visitor leaves the page.
 
 ## Verify Hotjar
 
-Filter DevTools Network by `hotjar`. After you allow measurement, the
-`hotjar-<siteId>.js` request loads from `static.hotjar.com`, and
-`window._hjSettings.hjid` holds your site ID. Review a recording of a real
-screen in your app to check that Hotjar masks the fields you expect.
-`window.hj` still exists after revocation, so check measurement permission
-before your own `hj` calls.
+Filter the DevTools Network panel by `hotjar`. After you allow measurement,
+the loader appears and `window._hjSettings.hjid` holds your site ID. If it
+holds a different ID, other code on the page set `_hjSettings` before c15t, and
+the helper left it alone. Find and remove that code. By default
+the loader is `hotjar-<siteId>.js` from `static.hotjar.com`. If you set
+`scriptUrl`, look for that URL instead.
+
+Then watch one recording of a real screen in your app. Hotjar decides what to
+mask, not c15t, so check that it hides the fields you expect.
+
+`window.hj` stays defined after withdrawal. If your own code calls `hj()`,
+check the measurement permission first.
 
 Test in a private window with an opt-in policy. Open DevTools Network, disable
 the cache and filter by the vendor's domain: