@c15t/nextjs 2.2.0 → 3.0.0-alpha.0

package/docs/guides/verify-consent.md

@@ -0,0 +1,62 @@
+---
+title: Verify consent before shipping
+description: Test requests, policy resolution, persistence, navigation and
+  preference changes in a production build.
+group: guides
+---
+
+## Establish the policy under test
+
+Use a fresh browser profile and a known policy. For an opt-in choice policy,
+optional requests should be absent before a choice. Opt-out and notice policies
+have different defaults; inspect the resolved rule rather than expecting every
+region to show the same banner. Keep test geography overrides out of production.
+
+Inventory scripts in your HTML, application code, tag manager, plugins and
+embeds. A c15t provider cannot make an independently loaded vendor wait for a
+choice. Remove duplicate loaders before interpreting the result.
+
+## Run the visitor flow
+
+| Action                                     | Check                                                                                    |
+| ------------------------------------------ | ---------------------------------------------------------------------------------------- |
+| Load without a stored choice               | Correct policy and prompt; category-gated vendors stay blocked when permission is denied |
+| Reject optional categories                 | Prompt closes; denied vendors remain blocked                                             |
+| Reload                                     | Valid rejection persists; no new choice event is emitted by hydration                    |
+| Reopen preferences                         | Settings remain reachable after the banner closes                                        |
+| Save one category                          | Only that category gets a new confirmation time                                          |
+| Navigate without reloading                 | One runtime remains active; no duplicate vendor initialization                           |
+| Revoke a grant                             | Future gated work stops and configured cleanup runs                                      |
+| Load with an expired or incompatible grant | It does not silently restore optional permissions                                        |
+| Block the consent backend                  | Failed resolution is observable; absence of a banner does not grant permission           |
+| Block browser storage                      | Interaction still works where supported; verify whether the choice survives reload       |
+
+Inspect Network before the page starts loading, with cache disabled for the test.
+Filter by the vendor's script and collection domains. Hiding an iframe after it
+loads is too late to prevent the initial request.
+
+Google Consent Mode integrations intentionally load their scripts and send
+consent signals. Test their default and update commands separately from a
+zero-request gate. See [Google Tag Manager](../integrations/google-tag-manager.md)
+and [Google Tag](../integrations/google-tag.md).
+
+## Test the production hosting shape
+
+For static sites, serve the generated files. Confirm no request depends on an
+API route or rewrite that only exists in development. For SSR, inspect the
+initial HTML and check that hydration does not change a valid stored choice.
+Test a direct visit as well as client navigation.
+
+For a cross-origin backend, check allowed origins, protocol and reachable URLs.
+A public backend URL is not an API secret. Keep credentials out of client props
+and public environment variables.
+
+## Check the interface
+
+Use a narrow viewport, long translated labels and keyboard-only navigation.
+Check that blocking dialogs trap focus, return it to the trigger when closed,
+and do not leave scrolling locked. Non-blocking notices should allow interaction
+with the page. Test contrast and focus indicators after applying a theme.
+
+Record the policy, framework, deployment and observed request behavior with the
+test result. "The banner appears" is only one assertion.

package/docs/integrations/adobe-analytics.md

@@ -1,160 +1,294 @@
 ---
 title: Adobe Analytics
-description: Adobe Analytics loaded through an Adobe Experience Platform Data
-  Collection Tags embed URL.
+description: Configure Adobe Analytics with c15t v3, understand measurement
+  permission and verify loading and revocation.
 group: integrations
-icon: adobe-analytics
 ---
-[Adobe Analytics](https://business.adobe.com/products/analytics/adobe-analytics.html) is commonly deployed through an Adobe Experience Platform Data Collection web property. Data Collection generates a property-specific Tags embed script, often hosted on `assets.adobedtm.com`, and that script can load Adobe Analytics, Web SDK, or other configured extensions and rules.
 
-## Integrate with c15t
+## Configure Adobe Analytics
 
-**React**
+Copy the full HTTPS embed URL for your Adobe Data Collection property environment. Replace the example URL; Adobe does not have a shared Analytics loader that only needs an account ID.
 
-```tsx
-import { type ReactNode } from 'react';
-import { ConsentManagerProvider } from '@c15t/react';
-import { adobeAnalytics } from '@c15t/scripts/adobe-analytics';
+| Package manager | Command                     |
+| :-------------- | :-------------------------- |
+| npm             | `npm install @c15t/scripts` |
+| pnpm            | `pnpm add @c15t/scripts`    |
+| yarn            | `yarn add @c15t/scripts`    |
+| bun             | `bun add @c15t/scripts`     |
 
-const scripts = [
-  adobeAnalytics({
-    scriptUrl:
-      'https://assets.adobedtm.com/YOUR_ORG/YOUR_PROPERTY/launch-production.min.js',
-  }),
-];
+```ts title="src/consent-scripts.ts"
+import { adobeAnalytics } from '@c15t/scripts/adobe-analytics';
 
-export function ConsentProvider({ children }: { children: ReactNode }) {
-  return (
-    <ConsentManagerProvider
-      options={{
-        mode: 'hosted',
-        backendURL: 'https://your-instance.c15t.dev',
-        scripts,
-      }}
-    >
-      {children}
-    </ConsentManagerProvider>
-  );
-}
+export const scripts = [adobeAnalytics({
+    scriptUrl: 'https://assets.adobedtm.com/YOUR_ORG/YOUR_PROPERTY/launch-production.min.js',
+  })];
 ```
 
+## 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 c15t owns loading once.
+
+The `scripts` export in `src/consent-scripts.ts` is a configuration, not an
+initializer. Add it to your existing consent owner using the registration point
+below. These are partial edits to that owner, not additional providers.
+
 **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
-'use client';
+<ConsentRoot state={state} config={consentConfig} scripts={scripts}>
+  {children}
+</ConsentRoot>
+```
 
-import { type ReactNode } from 'react';
-import { ConsentManagerProvider } from '@c15t/nextjs';
-import { adobeAnalytics } from '@c15t/scripts/adobe-analytics';
+For a Pages Router or static-export setup using `ConsentProvider`, add
+`scripts` to its existing `options` instead. Keep the router-specific setup
+from [Next.js script loading](../frameworks/next/script-loader.md).
+
+**TanStack Start**
 
-const scripts = [
-  adobeAnalytics({
-    scriptUrl:
-      'https://assets.adobedtm.com/YOUR_ORG/YOUR_PROPERTY/launch-production.min.js',
-  }),
-];
+In your existing root route component, import the scripts alongside
+`ConsentRoot`. Keep the server loader from the [TanStack Start quickstart](https://c15t.com/docs/frameworks/tanstack-start/quickstart).
+
+```tsx
+import { Outlet } from '@tanstack/react-router';
+import { ConsentRoot } from 'c15t/tanstack-start';
+import { scripts } from '../consent-scripts';
 
-export function ConsentProvider({ children }: { children: ReactNode }) {
+function Root() {
+  const state = Route.useLoaderData();
   return (
-    <ConsentManagerProvider
-      options={{
-        mode: 'hosted',
-        backendURL: '/api/c15t',
-        scripts,
-      }}
-    >
-      {children}
-    </ConsentManagerProvider>
+    <ConsentRoot state={state} backendURL={backendURL} initRoute={false} scripts={scripts}>
+      <Outlet />
+      {/* Keep your consent banner, dialog and preferences link here. */}
+    </ConsentRoot>
   );
 }
 ```
 
-**JavaScript**
+This edits the existing route. `Route` and `backendURL` come from its setup;
+keep the document shell and head components if they are part of your root.
+`initRoute={false}` keeps the quickstart's direct-backend initialization.
+If your app mounts a consent server route, retain its existing `initRoute`
+instead. Do not return script callbacks from a server function or route loader.
+
+**React**
+
+Import the scripts into your existing provider component:
 
 ```ts
-import { getOrCreateConsentRuntime } from 'c15t';
-import { adobeAnalytics } from '@c15t/scripts/adobe-analytics';
+import { ConsentProvider } from 'c15t/react';
+import { scripts } from './consent-scripts';
+```
+
+Keep the existing options and add `scripts`:
+
+```tsx
+<ConsentProvider options={{ ...consentOptions, scripts }}>
+  {children}
+</ConsentProvider>
+```
+
+Here `consentOptions` is your existing configuration, including
+`mode: hosted({ url: backendURL })`. Keep the banner, dialog and preferences
+link inside the provider. See [React script loading](https://c15t.com/docs/frameworks/react/script-loader).
+
+**Nuxt**
 
-getOrCreateConsentRuntime({
-  mode: 'hosted',
-  backendURL: 'https://your-instance.c15t.dev',
-  scripts: [
-    adobeAnalytics({
-      scriptUrl:
-        'https://assets.adobedtm.com/YOUR_ORG/YOUR_PROPERTY/launch-production.min.js',
-    }),
-  ],
+Attach one loader from the root `app.vue`, after the Nuxt module has
+started its browser runtime. This keeps vendor callbacks in application code rather
+than serialized `nuxt.config.ts` runtime configuration.
+
+```vue title="app/app.vue"
+<script setup lang="ts">
+import { onUnmounted } from 'vue';
+import { createScriptLoader } from 'c15t/modules/script-loader';
+import { scripts } from '../src/consent-scripts';
+
+const nuxtApp = useNuxtApp();
+const kernel = useConsentKernel();
+let loader: ReturnType<typeof createScriptLoader> | undefined;
+
+const removeMountedHook = nuxtApp.hook('app:mounted', () => {
+  loader = createScriptLoader({ kernel, scripts });
+});
+onUnmounted(() => {
+  removeMountedHook();
+  loader?.dispose();
 });
+</script>
+
+<template>
+  <ConsentRoot />
+  <NuxtPage />
+</template>
 ```
 
-## Find Your Embed URL
+Merge the setup code into your root and retain its footer and preferences
+link. `useConsentKernel` is auto-imported by the c15t Nuxt module. Adjust the
+relative script import if your `app.vue` is at the project root. This loader
+waits until the module has applied browser persistence and privacy signals,
+then reads the current snapshot and observes future changes. Do not also register these scripts
+in another loader. See the [Nuxt quickstart](https://c15t.com/docs/frameworks/nuxt/quickstart).
+
+**Vue**
+
+Use the kernel already provided by the Vue plugin. Merge this setup into
+`App.vue`, whose lifetime covers the application:
+
+```vue title="src/App.vue"
+<script setup lang="ts">
+import { onMounted, onUnmounted } from 'vue';
+import { createScriptLoader } from 'c15t/modules/script-loader';
+import { useConsentKernel } from 'c15t/vue/vue-plugin';
+import ConsentRoot from 'c15t/vue/consent-root';
+import { scripts } from './consent-scripts';
 
-Open Adobe Data Collection, choose your Tags property, then open **Environments**. Select the install action for the environment you want to deploy and copy the web property embed script URL from the generated code.
+const kernel = useConsentKernel();
+let loader: ReturnType<typeof createScriptLoader> | undefined;
 
-Each Adobe environment has its own embed code. Use the production URL in production, and keep development or staging URLs limited to test environments. The URL is typically shaped like:
+onMounted(() => {
+  loader = createScriptLoader({ kernel, scripts });
+});
+onUnmounted(() => loader?.dispose());
+</script>
 
-```txt
-https://assets.adobedtm.com/{org}/{property}/launch-{env}.min.js
+<template>
+  <ConsentRoot />
+  <main>Your application</main>
+</template>
 ```
 
-Self-hosted Data Collection builds are supported too. c15t only requires a full `https:` URL.
+Keep your existing page content and preferences link. The plugin still owns
+the kernel and persistence; this component owns only the vendor loader.
+Do not register the same scripts in plugin configuration as well. See the
+[Vue quickstart](https://c15t.com/docs/frameworks/vue/quickstart).
 
-## How c15t loads it
+**Astro**
 
-* **Category:** `measurement` (Analytics)
-* **Loads when:** measurement consent is granted
-* **On revocation:** unloaded - c15t removes the Adobe Tags script element from the DOM.
+Point the existing Astro integration at a client module. Keep its `mode`,
+`ui` and framework integration from the [Astro quickstart](https://c15t.com/docs/frameworks/astro/quickstart).
+Import `fileURLToPath` in your Astro configuration:
 
-The helper blocks the Adobe Tags library until measurement consent is granted. When measurement consent is revoked, c15t unloads the script element. Adobe rules, extensions, cookies, and downstream tags that already ran may have their own state, so configure Data Collection rules and extensions to respect your consent model as well.
+```js title="astro.config.mjs"
+import { fileURLToPath } from 'node:url';
+```
 
-This is the same caveat as tag managers: a Tags property can load more than Adobe Analytics. Keep non-measurement tags behind Adobe-side rule conditions, consent checks, or separate properties so they do not run from a measurement-only grant.
+Add this option to the existing `c15t({ ... })` call. Resolve the path from
+the configuration file because Astro injects the import into a virtual module:
 
-By default, c15t also seeds the Adobe Client Data Layer queue before loading:
+```js
+clientEntrypoint: fileURLToPath(new URL('./src/c15t.client.ts', import.meta.url)),
+```
 
-```ts
-adobeAnalytics({
-  scriptUrl:
-    'https://assets.adobedtm.com/YOUR_ORG/YOUR_PROPERTY/launch-production.min.js',
-  seedAdobeDataLayer: true,
-})
+Export the scripts from that module:
+
+```ts title="src/c15t.client.ts"
+import type { C15tClientOptionsExtension } from '@c15t/astro';
+import { scripts } from './consent-scripts';
+
+export default { scripts } satisfies C15tClientOptionsExtension;
 ```
 
-This creates `window.adobeDataLayer = []` only when it is still undefined. Adobe's Client Data Layer extension uses `adobeDataLayer` as the default object name, and the pre-seed is harmless for properties that do not use that extension.
+The integration passes this extension to its shared browser runtime. Vendor
+helpers contain callbacks, so do not put them in the serialized `scripts`
+option in `astro.config.mjs`. Keep one runtime across consent islands and
+`ClientRouter` navigation.
 
-Adobe's `_satellite` object becomes available after the Tags library loads:
+**Svelte**
 
-```ts
-if (window._satellite) {
-  // Adobe Tags runtime is available.
-}
+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 backendURL = import.meta.env.VITE_C15T_BACKEND_URL;
+  if (!backendURL) throw new Error('Set VITE_C15T_BACKEND_URL');
+  const mode = hosted({ url: backendURL });
+</script>
+
+<ConsentManagerProvider {mode} {scripts}>
+  <!-- Keep your application, consent UI and preferences link here. -->
+</ConsentManagerProvider>
 ```
 
-Use synchronous deployment only when a legacy Tags setup requires it:
+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: data.backendURL });
+</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`.
+For static hosting, keep your browser-only `mode` setup and omit request
+prefetch; the `scripts` prop stays the same. If you pass an externally owned
+`runtime` to the provider, register scripts when creating that runtime instead.
+
+**JavaScript**
+
+Attach the loader to your existing kernel before calling
+`kernel.commands.init()`:
 
 ```ts
-adobeAnalytics({
-  scriptUrl:
-    'https://assets.adobedtm.com/YOUR_ORG/YOUR_PROPERTY/launch-production.min.js',
-  async: false,
-})
+import { createScriptLoader } from 'c15t/modules/script-loader';
+import { scripts } from './consent-scripts';
+
+const loader = createScriptLoader({ kernel, scripts });
 ```
 
-## Types
+Call `loader.dispose()` when that application instance is destroyed.
+`kernel` is the hosted kernel from your quickstart. A provider-owned kernel
+already has a loader; do not attach a second one. See
+[JavaScript script loading](https://c15t.com/docs/frameworks/javascript/script-loader).
+
+## Options
 
-### AdobeAnalyticsOptions
+| Option               | Behavior                                                                 |
+| -------------------- | ------------------------------------------------------------------------ |
+| `scriptUrl`          | Required full HTTPS property embed URL. Invalid or non-HTTPS URLs throw. |
+| `async`              | Defaults to `true`.                                                      |
+| `seedAdobeDataLayer` | Defaults to `true`. Creates `window.adobeDataLayer` only if absent.      |
 
-|Property|Value|
-|:--|:--|
-|Type Name|\`AdobeAnalyticsOptions\`|
-|Source Path|\`./packages/scripts/src/vendors/analytics/adobe-analytics.ts\`|
+## Consent behavior
 
-\*ExtractedTypeTable: Could not extract "AdobeAnalyticsOptions" from "./packages/scripts/src/vendors/analytics/adobe-analytics.ts" using base path "/home/runner/work/c15t/c15t". Verify the path/name and that the file is included by your tsconfig.\*
+Measurement permission gates the property loader. Rules and extensions inside the Adobe property may load other services. Review those destinations and their purposes too; this helper does not assign separate consent categories to individual Adobe rules.
 
-### Script
+## Verify the integration
 
-|Property|Value|
-|:--|:--|
-|Type Name|\`Script\`|
-|Source Path|\`./packages/core/src/libs/script-loader/types.ts\`|
+Confirm the environment URL is correct and inspect requests from every enabled extension. Check that revoking permission stops application data-layer events; the helper does not call an Adobe shutdown API.
 
-\*ExtractedTypeTable: Could not extract "Script" from "./packages/core/src/libs/script-loader/types.ts" using base path "/home/runner/work/c15t/c15t". Verify the path/name and that the file is included by your tsconfig.\*
+Use a fresh session with an opt-in policy to check initial denial. Then grant
+`measurement`, revoke it, and reload. Inspect both network requests and future
+application events. Removing a script cannot undo code or requests that already
+ran. Follow the [consent verification guide](../guides/verify-consent.md).