@c15t/react 3.1.0 → 3.2.0

package/docs/frameworks/react/vendor-consent.md

@@ -157,6 +157,11 @@ const xPixelAllowed = useVendorAllowed('x-pixel');
 or the vendor list changed under the edit. Call `reset()` to start again.
 `useDeclaredVendors()` returns the declared vendors, and `useVendorChoice()`
 returns the recorded vendor decision, or `null` before the visitor made one.
+To list vendors under each category in your own preference center, call
+`useVendorsListedUnder(category)` from `c15t/react/headless`. It returns the
+vendors the stock dialog lists in that category's row, in declared order. A
+vendor known only from a script's `vendor` slug stays listed after the
+visitor turns it off, so they can turn it back on.
 
 A vendor reads as allowed only when it is declared, its category is allowed
 and the visitor has not switched it off. An id that nothing declares, in

package/docs/guides/banner-experiments.md

@@ -138,7 +138,7 @@ sends it with `/init`, and records it on the choices of visitors the banner
 showed it to, so you can compare opt-in rate and time to decision per arm.
 
 The same option exists in `c15t/next` (`ConsentRoot` `options`), `c15t/vue`,
-`@c15t/svelte`, the `c15t()` Astro integration from `c15t/astro`, and
+`c15t/svelte`, the `c15t()` Astro integration from `c15t/astro`, and
 `@c15t/browser`. On a server-rendered page in Next.js, TanStack Start or
 SvelteKit, pass it to `resolveConsent` instead, which counts the arm and hands
 it to the client; see [Vercel Flags SDK](#vercel-flags-sdk).
@@ -292,7 +292,7 @@ from [send the events to your own analytics](#send-the-events-to-your-own-analyt
 in `options`. The layout awaits consent inside `<Suspense>`, as in
 [render the banner in the server HTML](https://c15t.com/docs/frameworks/next/app-router#render-the-banner-in-the-server-html),
 so the banner is in the server HTML already showing the visitor's arm.
-`resolveConsent` in `c15t/tanstack-start/server` and `@c15t/svelte/server`
+`resolveConsent` in `c15t/tanstack-start/server` and `c15t/svelte/server`
 takes the same `experiment`.
 
 If you pass `resolveConsent()` to `ConsentRoot` without awaiting it (the
@@ -520,7 +520,7 @@ server has to know the arm. Pass the experiment to `resolveConsent`, as in
 [Vercel Flags SDK](#vercel-flags-sdk): it sends only `{ id, arm }` to the
 backend and hands the full experiment to the client in its state.
 `resolveConsent` takes `experiment` in `c15t/next/server`,
-`c15t/tanstack-start/server` and `@c15t/svelte/server`; Astro and Nuxt pass
+`c15t/tanstack-start/server` and `c15t/svelte/server`; Astro and Nuxt pass
 the arm they rendered on their own. When c15t picks the arm in the browser,
 the browser's own `/init` carries it, so a server-rendered page that skips
 the client `/init` has no count for built-in assignment. Resolve the arm with

package/docs/guides/troubleshooting.md

@@ -53,7 +53,7 @@ No banner is sometimes correct. Find out which case you have:
 | -------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
 | The backend request failed or has a CORS error     | Wrong backend URL, or your origin is not trusted                                                                                                                                                               | Copy the URL from your Inth project exactly, including any path. Add the site's origin, such as `https://www.example.com` or `http://localhost:3000`, to the project's trusted origins.                                                                |
 | Requests go to `your-project.inth.app` and fail    | The placeholder backend URL from the guides is still in your code                                                                                                                                              | Replace `https://your-project.inth.app` with the URL from your Inth project, including any path prefix.                                                                                                                                                |
-| No backend request at all                          | No provider mounted, the provider runs in offline mode, or the page resolved from a bundled manifest                                                                                                           | Check `window.c15t`. `mode: 'manifest'` with no request is expected for a policy that does not depend on location. Otherwise confirm your framework's backend URL variable is set, as [consent modes](../concepts/modes.md#set-the-backend-url) lists. |
+| No backend request at all                          | No provider mounted, the provider runs in local mode, or the page resolved from a bundled manifest                                                                                                             | Check `window.c15t`. `mode: 'manifest'` with no request is expected for a policy that does not depend on location. Otherwise confirm your framework's backend URL variable is set, as [consent modes](../concepts/modes.md#set-the-backend-url) lists. |
 | The policy resolved and no prompt is needed        | The visitor's location maps to a policy without a prompt, such as a US state without a privacy law in the recommended rules                                                                                    | Expected. Test from a location that needs a prompt. Server helpers such as Next.js `resolveConsent` accept a `country` override for testing; remove it before you deploy.                                                                              |
 | The policy resolved and a choice is stored         | A returning visitor                                                                                                                                                                                            | Expected. Clear site data or use a private window.                                                                                                                                                                                                     |
 | The banner is in the DOM but invisible or unstyled | c15t's rules are missing: `styles: false` without an imported stylesheet, a Content Security Policy that blocks c15t's `<style>` elements, Tailwind CSS 3's preflight, or a SvelteKit app without `c15tHandle` | See [stylesheets and CSS layers](../customization/stylesheets.md) for how your framework loads c15t's rules.                                                                                                                                           |
@@ -135,6 +135,7 @@ messages, prefixed with the integration's name, such as
 | `could not fetch the consent manifest from <url> during the build (fetch failed: ...)`, with `ENOTFOUND`, `ECONNREFUSED` or another network error | The build cannot reach the backend                                                                                              | Build where the backend is reachable, or deploy with `C15T_ON_BUILD_ERROR=runtime`                                                             |
 | `... (no response within 10 seconds)`                                                                                                             | The backend did not answer in time                                                                                              | Check the backend, or build where it is reachable                                                                                              |
 | `... (/manifest responded 404 Not Found)`, or another status                                                                                      | The URL is not your project's backend, such as the `https://your-project.inth.app` placeholder or a URL missing its path prefix | Copy the backend URL exactly as Inth shows it                                                                                                  |
+| `... (/manifest responded 402: <message> (<CODE>))`, or another status followed by a message                                                      | The backend refused the request and said why, such as an account out of its usage allowance                                     | Follow the backend's message                                                                                                                   |
 | `... (/manifest returned an invalid consent manifest.)`                                                                                           | The URL answered with something other than a consent manifest, such as an HTML page                                             | Point the backend URL at the backend itself, not your site or a dashboard page                                                                 |
 | `no backend URL is set, so the build cannot fetch the consent manifest. Pass backendURL or set ...`                                               | No `backendURL` option and no backend URL variable                                                                              | Set the variable your framework reads; see [consent modes](../concepts/modes.md#set-the-backend-url)                                           |
 | `skipped the consent manifest fetch because "/api/c15t" is not an absolute http(s) URL, so the server fetches the policy at runtime.`             | A relative backend URL. A notice, not an error.                                                                                 | Pass the absolute backend URL. With `onBuildError: 'fail'`, this stops the build with `build-time manifests require an absolute upstream URL.` |
@@ -176,7 +177,7 @@ instead of a factory:
 | Message                                                                                                                                                                                                               | Fix                                                                                                                                                                                                                                                                                            |
 | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | ``@c15t/react ConsentProvider: `mode` is required. Use manifest() or hosted().``                                                                                                                                      | Pass `mode`, such as `manifest()` from the same package. The start of the message names the package and the API that got no mode, such as `@c15t/svelte ConsentProvider` or `@c15t/core createConsentRuntime()`. Production builds name the package only: ``@c15t/react: `mode` is required.`` |
-| ``@c15t/browser: `mode` must be a factory, such as manifest(), hosted() or offline() from @c15t/browser. Mode names like "hosted" work only in the script-tag builds.``                                               | Import the factory and call it: `init({ mode: hosted() })`.                                                                                                                                                                                                                                    |
+| ``@c15t/browser: `mode` must be a factory, such as manifest(), hosted() or local() from @c15t/browser. Mode names like "hosted" work only in the script-tag builds.``                                                 | Import the factory and call it: `init({ mode: hosted() })`.                                                                                                                                                                                                                                    |
 | ``c15t: hosted() needs `backendURL`. Pass it, or add consentManifest() from c15t/build to your Vite config and set VITE_C15T_BACKEND_URL (or VITE_INTH_PROJECT_URL).``                                                | The React `hosted()` found no backend URL. `@c15t/browser` throws the same message prefixed `@c15t/browser:`. A production build prints only the first sentence.                                                                                                                               |
 | ``c15t: `mode` is the hosted() transport itself, so its code ships in the client bundle. Pass the hosted() your framework package exports instead: it is plain data, and the root loads the code only when it runs.`` | A warning outside production. A server-rendered root got a transport from `c15t/react`. Import the mode from your framework package. Next.js has its own wording; see [Next.js troubleshooting](https://c15t.com/docs/frameworks/next/troubleshooting).                                        |
 

package/docs/integrations/activecampaign.md

@@ -0,0 +1,297 @@
+---
+title: ActiveCampaign
+description: Load ActiveCampaign after marketing consent, configure its tracking
+  settings, and verify loading and withdrawal with c15t.
+seoTitle: ActiveCampaign cookie consent with c15t
+seoDescription: Gate ActiveCampaign on marketing consent with c15t. Configure
+  the loader, understand withdrawal limits, and verify vendor requests and
+  storage.
+icon: chart-line
+group: integrations
+---
+
+`activeCampaignTracking` waits for `marketing` consent before creating vendor globals or downloading ActiveCampaign.
+
+## Configure ActiveCampaign
+
+Copy the account ID from your ActiveCampaign site tracking snippet and remove the original snippet. Enable site tracking and authorize your site in ActiveCampaign.
+
+| 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 { activeCampaignTracking } from '@c15t/integrations/activecampaign';
+
+export const scripts = [
+	activeCampaignTracking({ accountId: 'YOUR_ACCOUNT_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                                                                                                                       |
+| ----------- | ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
+| `accountId` | Required                                                | ActiveCampaign account ID. Fixed once loading starts on this page.                                                             |
+| `email`     | Unset                                                   | Email for future requests, updated through `setEmail` after consent. Removing or blanking it clears the runtime's email field. |
+| `category`  | `marketing`                                             | Consent condition for the whole loader.                                                                                        |
+| `scriptUrl` | `https://diffuser-cdn.app-us1.com/diffuser/diffuser.js` | Regional or proxied loader URL. Blank values use the default. Fixed once loading starts on this page.                          |
+
+Missing or blank required values log an error and never load.
+
+## Loading and revocation
+
+After consent, the helper creates the callable `pgo` queue, sets its alias and timestamp, configures the account, and sets `setTrackByDefault(false)`. After the SDK loads it calls `process('allowTracking')`, which sends the page request itself. The helper sends no duplicate `process` call at initial load. Once tracking starts, a settled denial reported by an active registration requires a page reload. The helper sends no further tracking or email commands on that page, even after a regrant.
+
+Recreating the helper with the same options or a different `email` keeps the same SDK tag. After sign-in, register the helper with the contact's email. An email update changes future vendor requests and sends no additional page request. Omitting `email`, or passing a blank string, clears the runtime's email field after consent. This does not clear tracking cookies, reset the visitor ID, or erase identity already copied into vendor services.
+
+If another script replaces the captured `pgo` dispatcher, the helper sends no further commands and requires a page reload.
+
+Without a browser document, the script loader does not start ActiveCampaign. Replacing the helper or disposing its loader also requires no browser cleanup.
+
+Use one account, loader URL and contact email across registrations on the page. Every active registration must have its mapped consent before the helper enables tracking. Conflicting registrations withhold further helper commands. Resolving a conflict or remounting a registration does not send another page request on an already activated runtime. Changing `accountId` or `scriptUrl` after loading starts requires a new page; the helper logs the conflict and keeps the original SDK. A `category` change updates c15t eligibility, not vendor configuration. Consent and option updates settle after the current JavaScript turn.
+
+Keep `reloadOnConsentRevoked` enabled. The fetched runtime has no documented stop command. `setTrackByDefault(false)` does not stop services already started by `allowTracking`. Removing its script or registration cannot stop running code, clear stored identifiers or cancel requests. If a running helper changes to a denied category, reload the page as part of that configuration change. The helper logs that a reload is required; `reloadOnConsentRevoked` observes consent changes, not helper replacements. The permitted tag stays in the DOM across withdrawal and registration disposal to avoid installing a second runtime on remount. A pending download completed without consent or an active registration receives no `allowTracking` until a consenting registration exists and all active registrations agree on the configuration and have consent. An interrupted mount, failed download or externally detached SDK requires a page reload. The next denied page does not load the tag.
+
+ActiveCampaign uses first-party tracking cookies. Cookie names and other storage can vary with the vendor runtime and account configuration. Inspect your own deployment after grant.
+
+The default loads ActiveCampaign's Diffuser SDK directly from its vendor CDN. During verification, the `prism.js` URL from ActiveCampaign's tracking snippet redirected to `diffuser.js,?` and returned 403. The clean CDN URL returned JavaScript, accepted the same `pgo` queue, and initialized the tracker. The default bypasses that malformed redirect. Use `scriptUrl` for another region or a proxy and verify that it serves the matching ActiveCampaign runtime.
+
+## Verify ActiveCampaign
+
+Check for no `diffuser.js`, `pgo`, `prismGlobalObjectAlias`, cookies or browser storage before consent and after unrelated consent. Grant marketing and confirm the vendor runtime replaces the queue. Verify the page request with your own configured account. Revoke and check that the next denied page does not load the tracker.
+
+Sources: [tracking snippet](https://developers.activecampaign.com/reference/retrieve-site-tracking-code), [GDPR flow](https://help.activecampaign.com/hc/en-us/articles/360000872064-Site-tracking-and-the-GDPR), and [site tracking setup](https://help.activecampaign.com/hc/en-us/articles/20315300118044-How-to-set-up-Site-Tracking).
+
+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.