@c15t/react 3.0.0-alpha.9 → 3.0.0

package/docs/integrations/openai-pixel.md

@@ -3,22 +3,34 @@ title: OpenAI Pixel
 description: Load the ChatGPT Ads Measurement Pixel only after marketing consent
   with the c15t openaiPixel helper, guard oaiq conversion calls, and check it in
   DevTools.
+seoTitle: OpenAI Pixel cookie consent with c15t
+seoDescription: Load the OpenAI ChatGPT Ads Measurement Pixel only after
+  marketing consent. The c15t openaiPixel helper sends oaiq consent signals for
+  you.
 icon: chatgpt
 group: integrations
 ---
 
+The c15t `openaiPixel` helper keeps the OpenAI ChatGPT Ads Measurement Pixel off
+the page until `marketing` has consent. Until then, c15t does not define the
+`oaiq` queue. When `marketing` has consent, the helper queues
+`oaiq('consent', false)`, `init`, and `oaiq('consent', true)` before the SDK
+loads. If the visitor withdraws consent, the helper calls
+`oaiq('consent', false)`. The SDK stays on the page. By default, c15t also
+reloads the page.
+
 ## Configure the OpenAI Pixel
 
 Copy the pixel ID from the conversions tab in OpenAI Ads Manager. Remove the
 standalone OpenAI installation snippet, because the helper creates the `oaiq`
 queue and initializes the pixel itself.
 
-| 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`     |
+| 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 { openaiPixel } from '@c15t/integrations/openai-pixel';
@@ -33,51 +45,41 @@ 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.
+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**
 
-Import the configuration into the client boundary from your router guide:
-
-```ts
-import { ConsentRoot } from 'c15t/next';
-import { scripts } from './consent-scripts';
-```
+Add the configuration to `scripts` in `c15t.config.ts`, next to
+`next.config.ts`:
 
-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:
+```ts title="c15t.config.ts"
+import { defineConsentConfig } from 'c15t/next';
+import { scripts } from './src/consent-scripts';
 
-```tsx
-<ConsentRoot state={state} config={consentConfig} scripts={scripts}>
-  {children}
-</ConsentRoot>
+export default defineConsentConfig({ scripts });
 ```
 
-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
+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, `backendURL` and
-`initRoute` from the [TanStack Start quickstart](https://c15t.com/docs/frameworks/tanstack-start/quickstart):
+`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}
-  backendURL={backendURL}
-  initRoute={false}
-  scripts={scripts}
->
+<ConsentRoot state={consent} scripts={scripts}>
 ```
 
 Import vendor helpers in the root route module, not in a server function.
@@ -96,8 +98,8 @@ import { scripts } from './consent-scripts';
 <ConsentProvider options={{ mode, scripts }}>
 ```
 
-`mode` is the `hosted({ url: 'https://your-project.inth.app' })` value
-from the [React quickstart](../frameworks/react/quickstart.md). Keep the banner,
+`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).
 
@@ -126,15 +128,16 @@ callbacks. Write the vendor IDs into `consent-scripts.ts`. See
 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, {
-  backendURL: 'https://your-project.inth.app',
+  mode: manifest(),
   scripts,
 });
 ```
 
-Keep your existing backend URL and other options. The plugin starts one
+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).
@@ -142,12 +145,11 @@ choice. Do not also call `createScriptLoader` from a component. See
 **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.
+[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/consent-client.ts"
+```ts title="src/c15t.client.ts"
 import type { C15tClientOptionsExtension } from 'c15t/astro';
 import { scripts } from './consent-scripts';
 
@@ -167,15 +169,13 @@ pass them as a top-level prop:
 
 ```svelte title="src/App.svelte"
 <script lang="ts">
-  import { ConsentManagerProvider, hosted } from '@c15t/svelte';
+  import { ConsentProvider, manifest } from '@c15t/svelte';
   import { scripts } from './consent-scripts';
-
-  const mode = hosted({ url: 'https://your-project.inth.app' });
 </script>
 
-<ConsentManagerProvider {mode} {scripts}>
+<ConsentProvider mode={manifest()} {scripts}>
   <!-- Keep your application, consent UI and preferences link here. -->
-</ConsentManagerProvider>
+</ConsentProvider>
 ```
 
 Retain the styles and consent UI from the [Svelte quickstart](https://c15t.com/docs/frameworks/svelte/quickstart).
@@ -183,22 +183,21 @@ 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).
+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 { ConsentManagerProvider, hosted } from '@c15t/svelte';
+  import { ConsentRoot } 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}>
+<ConsentRoot state={data.consent} {scripts}>
   {@render children()}
   <!-- Keep your consent UI and preferences link here. -->
-</ConsentManagerProvider>
+</ConsentRoot>
 ```
 
 Import vendor helpers in the layout component, not in `+layout.server.ts`:
@@ -225,20 +224,19 @@ to a pasted snippet. See [HTML scripts](https://c15t.com/docs/frameworks/html/sc
 
 **JavaScript**
 
-Pass the scripts to `init()` from `@c15t/browser`, next to your backend
-URL:
+Pass the scripts to `init()` from `@c15t/browser`, next to your mode:
 
 ```ts
-import { init } from '@c15t/browser';
+import { init, manifest } from '@c15t/browser';
 import { scripts } from './consent-scripts';
 
 const consent = init({
-  backendURL: 'https://your-project.inth.app',
+  mode: manifest(),
   scripts,
 });
 ```
 
-Keep the backend URL from your quickstart. With
+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
@@ -248,7 +246,7 @@ A kernel you create yourself needs a loader from
 
 | Option      | Default                                     | Behavior                                                                                                                                                                                    |
 | ----------- | ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `pixelId`   | Required                                    | Pixel ID passed to `oaiq('init', ...)`. The helper trims it. Empty or whitespace-only values throw.                                                                                         |
+| `pixelId`   | Required                                    | Pixel ID passed to `oaiq('init', ...)`. The helper trims it. Empty or whitespace-only values log an error and the script does not load.                                                     |
 | `debug`     | `false`                                     | Logs SDK activity, including queued and dropped events, to the browser console.                                                                                                             |
 | `user`      | None                                        | User matching fields passed to `init`: `email_sha256`, `phone_number_sha256`, `external_id_sha256`, `first_name_sha256`, `last_name_sha256`, `country`, `city`, `region` and `postal_code`. |
 | `scriptSrc` | `https://bzrcdn.openai.com/sdk/oaiq.min.js` | SDK URL override. A blank value falls back to the default.                                                                                                                                  |
@@ -337,8 +335,8 @@ 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
+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/overview.md

@@ -2,6 +2,10 @@
 title: Integrations
 description: Find all c15t integrations for analytics, tag managers,
   advertising, email and SMS, chat and embedded content.
+seoTitle: Cookie consent integrations for analytics and ads | c15t
+seoDescription: Connect analytics, ad pixels, chat widgets and embeds to your
+  cookie banner. c15t has helpers for Google Tag Manager, Meta Pixel, PostHog,
+  Segment and Hotjar.
 group: integrations
 ---
 
@@ -12,12 +16,12 @@ register with your c15t provider. Importing a helper installs nothing on its
 own. Set up consent with your [framework quickstart](https://c15t.com/docs/frameworks) first,
 then follow the vendor guide.
 
-| 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`     |
+| Package manager | Command                          |
+| :-------------- | :------------------------------- |
+| npm             | `npm install @c15t/integrations` |
+| pnpm            | `pnpm add @c15t/integrations`    |
+| yarn            | `yarn add @c15t/integrations`    |
+| bun             | `bun add @c15t/integrations`     |
 
 `@c15t/integrations` is a separate package. Keep importing c15t itself from `c15t`,
 for example `c15t/react` or `c15t/next`.
@@ -40,41 +44,42 @@ kernel to control its DOM lifecycle. Embeds do not require `@c15t/integrations`.
 
 ## Tag managers
 
-| Integration                                   | Helper             | Category    | Loading behavior                                  |
-| --------------------------------------------- | ------------------ | ----------- | ------------------------------------------------- |
-| [Cloudflare Zaraz](./cloudflare-zaraz.md)     | `cloudflareZaraz`  | `necessary` | Always runs; syncs purposes, Zaraz runs the tools |
-| [Google Tag Manager](./google-tag-manager.md) | `googleTagManager` | `necessary` | Always loads; signals Google consent              |
+| Integration                                   | Helper             | Category                                             | Loading behavior                                                                                     |
+| --------------------------------------------- | ------------------ | ---------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
+| [Cloudflare Zaraz](./cloudflare-zaraz.md)     | `cloudflareZaraz`  | `necessary`                                          | Always runs; syncs purposes, Zaraz runs the tools                                                    |
+| [Google Tag Manager](./google-tag-manager.md) | `googleTagManager` | `necessary`; `measurement` or `marketing` when gated | Always loads and signals Google consent by default; `loadMode: 'after-consent'` waits for permission |
 
 ## Analytics
 
-| Integration                                               | Helper                   | Category                                        | Loading behavior                                                             |
-| --------------------------------------------------------- | ------------------------ | ----------------------------------------------- | ---------------------------------------------------------------------------- |
-| [Google Tag](./google-tag.md)                             | `gtag`                   | `measurement` or `marketing`                    | Always loads; signals Google consent                                         |
-| [Ahrefs Analytics](./ahrefs-analytics.md)                 | `ahrefsAnalytics`        | `measurement`                                   | Waits for effective permission                                               |
-| [Adobe Analytics](./adobe-analytics.md)                   | `adobeAnalytics`         | `measurement`                                   | Waits for effective permission                                               |
-| [Amplitude](./amplitude.md)                               | `amplitude`              | `measurement`                                   | Waits for effective permission; opts the SDK out on revocation               |
-| [Cloudflare Web Analytics](./cloudflare-web-analytics.md) | `cloudflareWebAnalytics` | `measurement`                                   | Waits for effective permission                                               |
-| [Clearbit](./clearbit.md)                                 | `clearbit`               | `marketing`                                     | Waits for effective permission                                               |
-| [Microsoft Clarity](./microsoft-clarity.md)               | `clarity`                | `measurement`                                   | Gated initially; keeps the SDK and signals storage consent                   |
-| [Databuddy](./databuddy.md)                               | `databuddy`              | `measurement`                                   | Always loads; switches the SDK's disabled flag                               |
-| [Fathom Analytics](./fathom-analytics.md)                 | `fathomAnalytics`        | `measurement`                                   | Waits for effective permission                                               |
-| [Heap](./heap.md)                                         | `heap`                   | `measurement`                                   | Waits for effective permission                                               |
-| [Matomo Analytics](./matomo-analytics.md)                 | `matomoAnalytics`        | `measurement`                                   | Gated by default; optional consent mode                                      |
-| [Mixpanel](./mixpanel-analytics.md)                       | `mixpanelAnalytics`      | `measurement`                                   | Always loads; calls opt-in and opt-out APIs                                  |
-| [OneDollarStats](./one-dollar-stats.md)                   | `oneDollarStats`         | `measurement`                                   | Waits for effective permission                                               |
-| [Hotjar](./hotjar.md)                                     | `hotjar`                 | `measurement`                                   | Waits for effective permission                                               |
-| [Hightouch](./hightouch.md)                               | `hightouch`              | `measurement`                                   | Waits for effective permission                                               |
-| [LogRocket](./logrocket.md)                               | `logRocket`              | `measurement`                                   | Waits for effective permission                                               |
-| [Plausible Analytics](./plausible-analytics.md)           | `plausibleAnalytics`     | `measurement`                                   | Waits for effective permission                                               |
-| [PostHog](./posthog.md)                                   | `posthog`                | `measurement`                                   | Configurable; defaults to always loading and calling opt-in and opt-out APIs |
-| [Promptwatch](./promptwatch.md)                           | `promptwatch`            | `measurement`                                   | Waits for effective permission                                               |
-| [Pirsch](./pirsch.md)                                     | `pirsch`                 | `measurement`                                   | Waits for effective permission                                               |
-| [RudderStack](./rudderstack.md)                           | `rudderstack`            | `measurement`                                   | Gated by default; optional destination consent mode                          |
-| [Segment](./segment.md)                                   | `segment`                | `measurement`                                   | Waits for effective permission                                               |
-| [Sentry](./sentry.md)                                     | `sentry`                 | `necessary`; Replay and user data `measurement` | Configurable; defaults to always loading and loads Replay after permission   |
-| [Rybbit Analytics](./rybbit-analytics.md)                 | `rybbitAnalytics`        | `measurement`                                   | Waits for effective permission                                               |
-| [Umami Analytics](./umami-analytics.md)                   | `umamiAnalytics`         | `measurement`                                   | Waits for effective permission                                               |
-| [Vercel Analytics](./vercel-analytics.md)                 | `vercelAnalytics`        | `measurement`                                   | Waits for effective permission                                               |
+| Integration                                               | Helper                   | Category                                        | Loading behavior                                                                                     |
+| --------------------------------------------------------- | ------------------------ | ----------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
+| [Google Tag](./google-tag.md)                             | `gtag`                   | `measurement` or `marketing`                    | Always loads and signals Google consent by default; `loadMode: 'after-consent'` waits for permission |
+| [Ahrefs Analytics](./ahrefs-analytics.md)                 | `ahrefsAnalytics`        | `measurement`                                   | Waits for effective permission                                                                       |
+| [Adobe Analytics](./adobe-analytics.md)                   | `adobeAnalytics`         | `measurement`                                   | Waits for effective permission                                                                       |
+| [Amplitude](./amplitude.md)                               | `amplitude`              | `measurement`                                   | Waits for effective permission; opts the SDK out on revocation                                       |
+| [Cloudflare Web Analytics](./cloudflare-web-analytics.md) | `cloudflareWebAnalytics` | `measurement`                                   | Waits for effective permission                                                                       |
+| [Clearbit](./clearbit.md)                                 | `clearbit`               | `marketing`                                     | Waits for effective permission                                                                       |
+| [Microsoft Clarity](./microsoft-clarity.md)               | `clarity`                | `measurement`                                   | Gated initially; keeps the SDK and signals storage consent                                           |
+| [Databuddy](./databuddy.md)                               | `databuddy`              | `measurement`                                   | Always loads; switches the SDK's disabled flag                                                       |
+| [Fathom Analytics](./fathom-analytics.md)                 | `fathomAnalytics`        | `measurement`                                   | Waits for effective permission                                                                       |
+| [Heap](./heap.md)                                         | `heap`                   | `measurement`                                   | Waits for effective permission                                                                       |
+| [Matomo Analytics](./matomo-analytics.md)                 | `matomoAnalytics`        | `measurement`                                   | Gated by default; optional consent mode                                                              |
+| [Mixpanel](./mixpanel-analytics.md)                       | `mixpanelAnalytics`      | `measurement`                                   | Always loads; calls opt-in and opt-out APIs                                                          |
+| [OneDollarStats](./one-dollar-stats.md)                   | `oneDollarStats`         | `measurement`                                   | Waits for effective permission                                                                       |
+| [Hotjar](./hotjar.md)                                     | `hotjar`                 | `measurement`                                   | Waits for effective permission                                                                       |
+| [Hightouch](./hightouch.md)                               | `hightouch`              | `measurement`                                   | Waits for effective permission                                                                       |
+| [LogRocket](./logrocket.md)                               | `logRocket`              | `measurement`                                   | Waits for effective permission                                                                       |
+| [Plausible Analytics](./plausible-analytics.md)           | `plausibleAnalytics`     | `measurement`                                   | Waits for effective permission                                                                       |
+| [PostHog](./posthog.md)                                   | `posthog`                | `measurement`                                   | Configurable; defaults to always loading and calling opt-in and opt-out APIs                         |
+| [Promptwatch](./promptwatch.md)                           | `promptwatch`            | `measurement`                                   | Waits for effective permission                                                                       |
+| [Pirsch](./pirsch.md)                                     | `pirsch`                 | `measurement`                                   | Waits for effective permission                                                                       |
+| [RudderStack](./rudderstack.md)                           | `rudderstack`            | `measurement`                                   | Gated by default; optional destination consent mode                                                  |
+| [Segment](./segment.md)                                   | `segment`                | `measurement`                                   | Waits for effective permission                                                                       |
+| [Sentry](./sentry.md)                                     | `sentry`                 | `necessary`; Replay and user data `measurement` | Configurable; defaults to always loading and loads Replay after permission                           |
+| [Rybbit Analytics](./rybbit-analytics.md)                 | `rybbitAnalytics`        | `measurement`                                   | Waits for effective permission                                                                       |
+| [Umami Analytics](./umami-analytics.md)                   | `umamiAnalytics`         | `measurement`                                   | Waits for effective permission                                                                       |
+| [Vercel Analytics](./vercel-analytics.md)                 | `vercelAnalytics`        | `measurement`                                   | Waits for effective permission                                                                       |
+| [Vercel Speed Insights](./vercel-speed-insights.md)       | `vercelSpeedInsights`    | `measurement`                                   | Waits for effective permission; drops reports after revocation                                       |
 
 ## Chat and support
 
@@ -111,16 +116,28 @@ manager entry before adding its helper. c15t cannot gate a copy it did not
 load. Tag managers and data pipelines such as Segment can load further
 destinations, which need consent settings of their own.
 
+Framework packages are loaders too. To move their vendors to c15t, see
+[migrate from `@next/third-parties`](https://c15t.com/docs/frameworks/next/scripts#migrate-from-nextthird-parties)
+for Next.js, and
+[migrate from `@nuxt/scripts`](https://c15t.com/docs/frameworks/nuxt/scripts#migrate-from-nuxtscripts)
+or [migrate from `nuxt-gtag`](https://c15t.com/docs/frameworks/nuxt/scripts#migrate-from-nuxt-gtag)
+for Nuxt.
+
 When a visitor turns off a category they had allowed, c15t reloads the page so
 that code which already ran stops. Each vendor guide lists what its helper does
 on revocation and how to check it.
 
 ## Vendor switches and cookie cleanup
 
-Every helper sets a `vendor` slug, so once you declare that vendor a visitor
-can allow its category and still switch the vendor off. Gating also leaves
-behind the cookies a vendor already wrote; `clearOnRevocation` deletes them
-when their category is denied. Each framework documents both in its Scripts
+Every helper sets a `vendor` slug and the vendor's name and privacy policy, so
+the preference dialog lists the vendor with its own switch. A visitor can allow
+a category and still switch one vendor off. c15t then does not load that
+vendor's script. Helpers that load on every page, such as Google Tag Manager,
+Microsoft UET and Mixpanel, still load and send the vendor a denied signal
+instead. The dialog lists `necessary` helpers without a switch. Declare
+a vendor with the same slug to replace its name and links, for example when you
+self-host Matomo or PostHog. Gating also leaves behind the cookies a vendor
+already wrote; `clearOnRevocation` deletes them when their category is denied. Each framework documents both in its Scripts
 and embeds group:
 
 | Framework      | Vendor consent                                                                   | Clear on revocation                                                                        |