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

package/docs/integrations/klaviyo.md

@@ -0,0 +1,486 @@
+---
+title: Klaviyo
+description: Load Klaviyo signup forms and onsite tracking only after marketing
+  and measurement consent with the c15t klaviyo helper, gate your own events,
+  and check it in DevTools.
+icon: klaviyo
+group: integrations
+---
+
+## Configure Klaviyo
+
+Copy the six-character public API key, also called the site ID, from
+**Settings > Account > API keys** in Klaviyo. It appears in every page that
+loads Klaviyo, so it is safe in browser code. Never put a private key
+(`pk_...`) in the browser; the helper throws if you pass one.
+
+| Package manager | Command                                |
+| :-------------- | :------------------------------------- |
+| npm             | `npm install @c15t/integrations@alpha` |
+| pnpm            | `pnpm add @c15t/integrations@alpha`    |
+| yarn            | `yarn add @c15t/integrations@alpha`    |
+| bun             | `bun add @c15t/integrations@alpha`     |
+
+```ts title="src/consent-scripts.ts"
+import { klaviyo } from '@c15t/integrations/klaviyo';
+
+export const scripts = [klaviyo({ publicApiKey: 'YOUR_PUBLIC_API_KEY' })];
+```
+
+Remove Klaviyo's own snippet first. On Shopify, BigCommerce, WooCommerce and
+the other platforms where Klaviyo installs Klaviyo.js for you, turn that
+installation off, or c15t is not the only thing loading it.
+
+## Register the scripts
+
+Complete your [framework quickstart](https://c15t.com/docs/frameworks) first. Keep its Inth
+endpoint, policy, styles and consent UI. Remove the vendor's original script,
+SDK initializer or tag-manager entry, so the vendor loads only through c15t.
+
+The vendor pages put the helper in `src/consent-scripts.ts`. If your framework
+quickstart already created a scripts file, such as `lib/scripts.ts` in the
+Next.js guide, add the helper to that array instead of creating a second file.
+The `scripts` export is a configuration, not an initializer. Add it to the c15t provider you already have, at the registration
+point for your framework below. These are edits to that provider, not a second
+provider.
+
+**Next.js**
+
+Import the configuration into the client boundary from your router guide:
+
+```ts
+import { ConsentRoot } from 'c15t/next';
+import { scripts } from './consent-scripts';
+```
+
+Keep the server-resolved `state` and shared `consentConfig` from your
+router guide. Its manifest, init and save URLs stay in effect. Add
+`scripts` as a top-level prop on the existing root:
+
+```tsx
+<ConsentRoot state={state} config={consentConfig} scripts={scripts}>
+  {children}
+</ConsentRoot>
+```
+
+App Router, Pages Router and static export all use this `ConsentRoot` in
+the `'use client'` wrapper `components/consent.tsx`. Keep `scripts` there,
+because a Server Component cannot pass script callbacks to it. See
+[Next.js scripts and embeds](../frameworks/next/scripts.md).
+
+**TanStack Start**
+
+Import the configuration into your root route and pass it to the existing
+`ConsentRoot` as a top-level prop. Keep the loader, `backendURL` and
+`initRoute` from the [TanStack Start quickstart](https://c15t.com/docs/frameworks/tanstack-start/quickstart):
+
+```tsx title="src/routes/__root.tsx"
+import { scripts } from '../consent-scripts';
+
+<ConsentRoot
+  state={consent}
+  backendURL={backendURL}
+  initRoute={false}
+  scripts={scripts}
+>
+```
+
+Import vendor helpers in the root route module, not in a server function.
+A server function's return value must be serializable, and script
+configurations carry callbacks. See
+[TanStack Start scripts](../frameworks/tanstack-start/scripts.md).
+
+**React**
+
+Add the configuration to the existing `ConsentProvider` options, next to
+`mode`:
+
+```tsx title="src/consent.tsx"
+import { scripts } from './consent-scripts';
+
+<ConsentProvider options={{ mode, scripts }}>
+```
+
+`mode` is the `hosted({ url: 'https://your-project.inth.app' })` value
+from the [React quickstart](https://c15t.com/docs/frameworks/react/quickstart). Keep the banner,
+dialog and preferences link inside the provider. See
+[React scripts and embeds](../frameworks/react/scripts.md).
+
+**Nuxt**
+
+Register the scripts under the `c15t` key in `app/app.config.ts`. Adjust the
+relative import to where you created `consent-scripts.ts`:
+
+```ts title="app/app.config.ts"
+import { scripts } from '../src/consent-scripts';
+
+export default defineAppConfig({
+  c15t: { scripts },
+});
+```
+
+The Nuxt module merges this over its options in `nuxt.config.ts` and starts
+one script loader in the browser after hydration, once it has applied the
+visitor's stored choice and privacy signals. Keep `scripts` out of
+`nuxt.config.ts`, which reaches the browser as JSON and drops the vendor
+callbacks. Write the vendor IDs into `consent-scripts.ts`. See
+[Nuxt scripts and embeds](../frameworks/nuxt/scripts.md).
+
+**Vue**
+
+Pass the scripts to the existing `c15tVue` plugin call in `src/main.ts`:
+
+```ts title="src/main.ts"
+import { scripts } from './consent-scripts';
+
+app.use(c15tVue, {
+  backendURL: 'https://your-project.inth.app',
+  scripts,
+});
+```
+
+Keep your existing backend URL and other options. The plugin starts one
+script loader when the app mounts, after it has applied the visitor's stored
+choice. Do not also call `createScriptLoader` from a component. See
+[Vue scripts and embeds](../frameworks/vue/scripts.md).
+
+**Astro**
+
+Add the scripts to the client entrypoint from the
+[Astro quickstart](https://c15t.com/docs/frameworks/astro/quickstart), the module that the
+integration's `clientEntrypoint` option names. Keep `mode`, `ui` and the
+framework integration in `astro.config.mjs` as they are. If the module
+already exports scripts, combine the two arrays.
+
+```ts title="src/consent-client.ts"
+import type { C15tClientOptionsExtension } from 'c15t/astro';
+import { scripts } from './consent-scripts';
+
+export default { scripts } satisfies C15tClientOptionsExtension;
+```
+
+Vendor helpers contain callbacks, and the integration options in
+`astro.config.mjs` are serialized into the page, so do not put helpers in
+the integration's `scripts` option. The integration passes the client
+entrypoint to the one runtime every page shares, including across
+`ClientRouter` navigation.
+
+**Svelte**
+
+Import the scripts in the component that owns your existing provider and
+pass them as a top-level prop:
+
+```svelte title="src/App.svelte"
+<script lang="ts">
+  import { ConsentManagerProvider, hosted } from '@c15t/svelte';
+  import { scripts } from './consent-scripts';
+
+  const mode = hosted({ url: 'https://your-project.inth.app' });
+</script>
+
+<ConsentManagerProvider {mode} {scripts}>
+  <!-- Keep your application, consent UI and preferences link here. -->
+</ConsentManagerProvider>
+```
+
+Retain the styles and consent UI from the [Svelte quickstart](https://c15t.com/docs/frameworks/svelte/quickstart).
+The provider owns the loader and disposes it on unmount.
+
+**SvelteKit**
+
+Add the scripts to the existing root layout provider. Keep the server load
+and its serializable prefetch data from the [SvelteKit quickstart](https://c15t.com/docs/frameworks/sveltekit/quickstart).
+
+```svelte title="src/routes/+layout.svelte"
+<script lang="ts">
+  import { ConsentManagerProvider, hosted } from '@c15t/svelte';
+  import { scripts } from '../consent-scripts';
+
+  let { children, data } = $props();
+  const mode = hosted({ url: 'https://your-project.inth.app' });
+</script>
+
+<ConsentManagerProvider {mode} {scripts} prefetch={data.prefetch}>
+  {@render children()}
+  <!-- Keep your consent UI and preferences link here. -->
+</ConsentManagerProvider>
+```
+
+Import vendor helpers in the layout component, not in `+layout.server.ts`:
+a server load cannot send functions to the browser. Prerendered, static and
+SPA-mode pages use the same `scripts` prop. If you pass an externally owned
+`runtime` to the provider, register scripts when creating that runtime instead.
+
+**HTML**
+
+The helpers in `@c15t/integrations` are ES modules that need a bundler. On a
+page that loads the c15t script tag, paste the vendor's own snippet instead
+and keep it inert until its category is allowed:
+
+```html
+<script type="text/plain" data-c15t-category="measurement">
+  // The vendor's snippet, unchanged
+</script>
+```
+
+Use the category this guide names for the vendor. c15t runs the snippet
+once that category is allowed, and reloads the page when the visitor
+withdraws it. Helper options on this page, such as `loadMode`, do not apply
+to a pasted snippet. See [HTML scripts](../frameworks/html/scripts.md).
+
+**JavaScript**
+
+Pass the scripts to `init()` from `@c15t/browser`, next to your backend
+URL:
+
+```ts
+import { init } from '@c15t/browser';
+import { scripts } from './consent-scripts';
+
+const consent = init({
+  backendURL: 'https://your-project.inth.app',
+  scripts,
+});
+```
+
+Keep the backend URL from your quickstart. With
+`createConsentRuntime` from `c15t/runtime`, pass `scripts` to it instead.
+A kernel you create yourself needs a loader from
+`c15t/modules/script-loader`. Attach one loader per kernel. See
+[JavaScript scripts](../frameworks/javascript/scripts.md).
+
+## Options
+
+| Option         | Default                                                                      | Behavior                                                                                                                                                  |
+| -------------- | ---------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `publicApiKey` | Required                                                                     | Six-letter-or-digit public API key. Surrounding whitespace is trimmed. Any other value throws, with a separate message for private keys.                  |
+| `mode`         | `'full'`                                                                     | `'full'` loads forms and web tracking. `'forms-only'` turns Klaviyo's web tracking off before the bundle starts; see [forms-only mode](#forms-only-mode). |
+| `category`     | `{ and: ['marketing', 'measurement'] }`, or `'marketing'` in forms-only mode | Consent condition that must hold before Klaviyo.js loads. Accepts any category or `and`/`or`/`not` condition.                                             |
+| `scriptUrl`    | `https://static.klaviyo.com/onsite/js/<publicApiKey>/klaviyo.js`             | Loader URL override, such as a first-party proxy. Must be `https:`. A blank value falls back to the default.                                              |
+
+## Why Klaviyo needs two categories
+
+One script, Klaviyo.js, serves both signup forms and Active on Site tracking.
+Klaviyo offers no setting or browser API to load one without the other. Forms
+grow your marketing lists, and tracking records which identified visitors are
+on the site and feeds segments, attribution and automated email and SMS flows.
+Klaviyo classifies its `__kla_id` cookie as a targeting cookie.
+
+So by default `klaviyo` loads only when both marketing and measurement are
+allowed. With either category alone, or neither, c15t requests nothing from
+Klaviyo and Klaviyo writes no storage. Once the second category is allowed,
+Klaviyo.js loads without a page reload, once.
+
+If your legal review classifies Klaviyo differently, or your account uses only
+part of it, pass your own condition:
+
+```ts
+klaviyo({ publicApiKey: 'YOUR_PUBLIC_API_KEY', category: 'marketing' });
+```
+
+## Forms-only mode
+
+`mode: 'forms-only'` loads Klaviyo.js once marketing is allowed and sets
+Klaviyo's `__kla_off=true` cookie before the bundle runs. Klaviyo documents
+this cookie as the switch that keeps forms working while it stops tracking.
+
+```ts
+klaviyo({ publicApiKey: 'YOUR_PUBLIC_API_KEY', mode: 'forms-only' });
+```
+
+In this mode Klaviyo.js sends no Active on Site events, and `identify` and
+`track` calls send nothing. It is not a cookieless mode:
+
+* Klaviyo.js still writes an anonymous `__kla_id` cookie, plus the Web Storage
+  keys listed in [storage](#storage-klaviyo-writes).
+* Form views and steps are still reported to Klaviyo's form analytics, and
+  each report carries the anonymous visitor ID from `__kla_id`.
+* Forms cannot target by visitor type, such as hiding a form from existing
+  subscribers.
+* A submission still creates the profile and records the subscription, but
+  the browser stays unidentified, so Klaviyo records no onsite activity for
+  that person afterwards.
+* The mode is fixed when the page loads. Allowing measurement later does not
+  turn tracking on. Switch to `mode: 'full'` in your configuration for that.
+* `__kla_off` is a session cookie, and the helper never deletes it, since a
+  site or visitor may also set it to opt out. If you move a site from
+  forms-only to full mode, visitors who saw the forms-only version keep
+  tracking off until they close the browser.
+
+There is no measurement-only mode. Klaviyo cannot suppress published forms
+while still tracking visitors.
+
+## Vendor switches, opt-out regions and IAB mode
+
+The helper sets the vendor slug `klaviyo`, so a visitor can allow marketing
+and measurement and still switch Klaviyo off. Declare the vendor with a name
+and privacy policy URL so your preference UI can show the switch; until then
+c15t logs a warning in the console. See
+[vendor consent for your framework](./overview.md#vendor-switches-and-cookie-cleanup).
+
+* With the switch off, Klaviyo.js does not load. Switching it off after
+  Klaviyo has loaded reloads the page, and the new page loads nothing from
+  Klaviyo.
+* `clearOnRevocation` runs per category, so switching off only the vendor
+  leaves `__kla_id` and Klaviyo's other storage in place. Klaviyo stops reading
+  them because it no longer loads.
+* In regions whose policy allows marketing and measurement before a choice,
+  such as most of the US, Klaviyo.js loads on the first page view. A visitor
+  sending Global Privacy Control has both denied, so Klaviyo does not load.
+* In IAB TCF mode, vendor switches are ignored. Klaviyo has no TCF vendor ID
+  in this helper, so it loads once the TCF purposes behind marketing (2, 3
+  and 4) and measurement (7, 8 and 9) are all granted.
+
+## Send your own events only with consent
+
+The helper never calls `identify`, `track` or Klaviyo's Viewed Product and
+Added to Cart snippets. Send them from your own code.
+
+Before Klaviyo.js loads, the helper installs the `klaviyo` object from
+Klaviyo's onsite snippet. Calls made before the bundle arrives are queued, and
+Klaviyo.js replays them. The object exists only after the helper's consent
+condition held on this page, so optional chaining drops calls made without
+consent:
+
+```ts
+window.klaviyo?.track('Added to Cart', {
+	ProductName: product.name,
+	Price: product.price,
+});
+```
+
+This check assumes c15t reloads the page on revocation, which it does by
+default. With `reloadOnConsentRevoked: false`, the object stays after a
+revocation, so check the categories with your framework's consent API before
+each call. In forms-only mode, Klaviyo drops these calls even though the
+object exists.
+
+## Account settings that change what Klaviyo collects
+
+c15t controls when Klaviyo.js loads. These Klaviyo account settings control
+what it does once loaded:
+
+* **Anonymous visitor activity backfill** stores frontend events for
+  unidentified visitors in local storage (`kl-post-identification-sync`) for
+  up to 14 days, then sends them when the visitor is identified. Klaviyo says
+  this needs both analytics and marketing consent. Turn it off under
+  **Settings > Account > Data**, *Enable anonymous visitor tracking*.
+* **Extended ID** and **First-Party ID** restore an identity after `__kla_id`
+  expires; First-Party ID adds a `__kle_id` cookie. Klaviyo recommends
+  updating your cookie notice before enabling either.
+* **Email and SMS click tracking** identifies visitors who arrive from a
+  Klaviyo message through the `_kx` URL parameter. It can only be turned off
+  for the whole account.
+
+## Cookie consent is not subscription consent
+
+Your c15t banner asks whether Klaviyo may run in the browser. A Klaviyo signup
+form asks whether someone wants your emails or texts. They are separate
+records: allowing marketing cookies does not subscribe anyone, and a
+subscription does not grant cookie consent. Keep collecting email and SMS
+consent in Klaviyo forms, with the wording your channels require.
+
+## Storage Klaviyo writes
+
+Observed with Klaviyo.js in October 2026. Klaviyo can change these names.
+
+| Storage         | Names                                                                                                                                                                         |
+| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Cookies         | `__kla_id` (up to two years after identification), `__kle_id` with First-Party ID, `__kla_off` in forms-only mode, `datadome` after a form submission triggers bot protection |
+| Local storage   | `klaviyoOnsite`, `__kl_key`, `$referrer`, `$last_referrer`, `kl-post-identification-sync`, `ddSession`                                                                        |
+| Session storage | `klaviyoPagesVisitCountV2`, `klaviyoFormSubmit`, `_kx`, `ddCookieCandidateDomain`                                                                                             |
+
+The `datadome` and `dd*` names come from DataDome, the bot protection Klaviyo
+runs on form submissions.
+
+To delete them when a visitor turns either category off, add them to
+`clearOnRevocation` under both categories:
+
+```ts
+const klaviyoStorage = {
+	cookies: ['__kla_id', '__kle_id', 'datadome'],
+	localStorage: [
+		'klaviyoOnsite',
+		'__kl_key',
+		'$referrer',
+		'$last_referrer',
+		'kl-post-identification-sync',
+		'ddSession',
+	],
+	sessionStorage: [
+		'klaviyoPagesVisitCountV2',
+		'klaviyoFormSubmit',
+		'_kx',
+		'ddCookieCandidateDomain',
+	],
+};
+
+const clearOnRevocation = {
+	marketing: klaviyoStorage,
+	measurement: klaviyoStorage,
+};
+```
+
+See [clear on revocation for your framework](./overview.md#vendor-switches-and-cookie-cleanup)
+for where the option goes. In forms-only mode, list the storage under
+`marketing` only.
+
+## Content Security Policy
+
+Klaviyo.js appends its modules as new script elements without a nonce. A
+popup signup form with default styling used these hosts in testing:
+
+| Directive     | Hosts                                                                                     |
+| ------------- | ----------------------------------------------------------------------------------------- |
+| `script-src`  | `https://static.klaviyo.com`, `https://static-tracking.klaviyo.com`                       |
+| `connect-src` | `https://a.klaviyo.com`, `https://fast.a.klaviyo.com`, `https://static-forms.klaviyo.com` |
+| `style-src`   | `https://static.klaviyo.com`, `https://fonts.googleapis.com`                              |
+| `img-src`     | `https://d3k81ch9hvuctc.cloudfront.net`                                                   |
+| `frame-src`   | `https://geo.captcha-delivery.com`, for the bot check some submissions get                |
+
+When DataDome, the bot protection Klaviyo runs on submissions, challenges a
+visitor, it loads its check in a frame. Fonts, images and features differ
+between forms, so test each published form under your policy.
+
+## Verify Klaviyo
+
+Filter DevTools Network by `klaviyo`:
+
+1. Allow marketing only. Nothing loads from Klaviyo, and the Application tab
+   shows no `__kla_id` cookie.
+2. Allow measurement too. `klaviyo.js` loads from
+   `static.klaviyo.com/onsite/js/<your key>/`, followed by Klaviyo's modules
+   from `static.klaviyo.com` and `static-tracking.klaviyo.com`.
+3. In full mode, `await klaviyo.account()` in the console returns your public
+   API key. In forms-only mode it returns `null`.
+4. A published signup form appears in both modes. The form request goes to
+   `static-forms.klaviyo.com/forms/api/v7/<your key>/full-forms`.
+5. In forms-only mode, the console shows Klaviyo's warning that tracking is
+   disabled, and an `identify` call sends no request to
+   `a.klaviyo.com/client/`.
+
+Test in a private window with an opt-in policy. Open DevTools Network, disable
+the cache and filter by the vendor's domain:
+
+1. Load the page. No request goes to the vendor before you choose.
+2. Click Reject, then reload. There is still no vendor request.
+3. Open Privacy settings and allow the helper's category. The vendor script
+   loads without a page reload.
+4. Turn the category off again and save. c15t reloads the page, and the new
+   page makes no vendor request.
+
+c15t reloads on revocation because removing a script element does not stop
+code that already ran. The vendor's listeners, timers and queued events stay
+alive until the page unloads. If you set `reloadOnConsentRevoked: false`, stop
+the vendor yourself. Register a callback-only script whose `onConsentChange`
+calls the vendor's opt-out API, as shown in
+[custom integrations](./building-integrations.md), and check the
+permission before each of your own event calls. The reload does not delete
+cookies the vendor already set; see
+[clear on revocation for your framework](./overview.md#vendor-switches-and-cookie-cleanup).
+
+The helper sets `vendor` to its script ID, so once you declare that vendor a
+visitor can turn it off inside an allowed category. See
+[vendor consent for your framework](./overview.md#vendor-switches-and-cookie-cleanup). The
+[consent verification guide](../guides/verify-consent.md) covers navigation,
+expiry and hosting checks.