@c15t/react 3.2.0-canary.0 → 3.2.1

package/docs/integrations/adobe-target.md

@@ -0,0 +1,460 @@
+---
+title: Adobe Target
+description: Gate a self-hosted Adobe Target at.js download or Adobe Experience
+  Platform Web SDK on experience consent, send consent updates and check
+  revocation limits.
+seoTitle: Adobe Target cookie consent with c15t
+seoDescription: Load Adobe Target after experience consent with c15t. Configure
+  at.js opt-in or Web SDK setConsent, and understand what revocation can stop.
+icon: bullseye
+group: integrations
+---
+
+Adobe Target runs A/B tests and personalizes page content. The c15t
+`adobeTarget` helper waits for `experience` consent before it creates Adobe
+globals or requests the SDK. Pick one mode per page: your self-hosted `at.js`
+file or Adobe Experience Platform Web SDK.
+
+On withdrawal, the helper denies Target through Adobe's Opt-in service for
+at.js, or sends `setConsent` with `'out'` for Web SDK. Neither undoes content
+Target already changed, so keep `reloadOnConsentRevoked` enabled.
+
+## Configure Adobe Target
+
+Remove the original loader, any Adobe Tags rule and any Web SDK prehiding
+snippet for this installation. A separate Adobe installation can make requests
+before c15t has permission. Without the prehiding snippet, visitors see the
+original page first, then Target's changes once consent allows the SDK to load.
+
+| Package manager | Command                          |
+| :-------------- | :------------------------------- |
+| npm             | `npm install @c15t/integrations` |
+| pnpm            | `pnpm add @c15t/integrations`    |
+| yarn            | `yarn add @c15t/integrations`    |
+| bun             | `bun add @c15t/integrations`     |
+
+### at.js
+
+Download `at.js` from **Administration > Implementation** in Adobe Target,
+then host the file on your own site. Adobe provides no shared CDN URL for
+`at.js`. Use at.js 1.7.0 or 2.1.0 and later for Opt-in support. Adobe excludes
+2.0.0 and 2.0.1 from this support.
+
+```ts title="src/consent-scripts.ts"
+import { adobeTarget } from '@c15t/integrations/adobe-target';
+
+export const scripts = [
+	adobeTarget({
+		mode: 'atjs',
+		scriptUrl: '/scripts/at.js',
+		targetGlobalSettings: { secureOnly: true },
+	}),
+];
+```
+
+The helper writes `window.targetGlobalSettings` before it appends the loader
+and forces `optinEnabled: true`. Pass the rest of your supported settings in
+`targetGlobalSettings`. The helper replaces any previous settings object.
+
+Adobe's Opt-in service is part of the Experience Cloud ID (ECID) service. If
+that service is on the page, the helper calls
+`adobe.optIn.approve(adobe.OptInCategories.TARGET)` before it loads at.js and
+`adobe.optIn.deny(adobe.OptInCategories.TARGET)` on revocation. It leaves the
+permissions for ECID and other Adobe products alone. The helper doesn't load
+or configure the ID service. Any ID service deployment needs its own consent
+gate and Adobe configuration.
+
+Without that service, `optinEnabled` alone gives no runtime stop API. c15t
+still gates the at.js download, but only the page reload stops an at.js that
+is already running.
+
+### Web SDK
+
+As an alternative to at.js, enable Adobe Target on your datastream in Adobe
+Data Collection. Copy the datastream ID and organization ID, then choose an
+exact Web SDK version of `2.21.0` or later from Adobe's
+[release notes](https://experienceleague.adobe.com/en/docs/experience-platform/collection/js/release-notes).
+
+```ts title="src/consent-scripts.ts"
+import { adobeTarget } from '@c15t/integrations/adobe-target';
+
+export const scripts = [
+	adobeTarget({
+		datastreamId: 'YOUR_DATASTREAM_ID',
+		mode: 'websdk',
+		orgId: 'YOUR_ORG_ID@AdobeOrg',
+		version: '2.30.0',
+	}),
+];
+```
+
+Version `2.30.0` is an example. It doesn't update itself. The helper loads the
+minified library from Adobe's CDN for the version you pass. Versions before
+`2.21.0` need `edgeConfigId` instead of the `datastreamId` key this helper
+configures. Older versions, ranges, aliases and prerelease versions log an
+error and skip the loader.
+
+Once consent allows the loader, the helper creates the `alloy` base code.
+After the SDK loads, it calls `alloy('configure')` with your IDs and
+`defaultConsent: 'pending'`. Once configuration succeeds, it sends
+`alloy('setConsent')` using Adobe 1.0 consent with the latest permitted state.
+If consent was withdrawn during configuration, that state is `'out'`.
+
+Consent updates run one at a time. If the choice changes while a command is
+pending, the helper sends the latest choice after that command settles. A
+rejected `setConsent` logs an error and can retry on a later consent change.
+The helper schedules no automatic retries and can't recover an operation
+stalled inside Adobe. Reload if commands stay pending. A failed configuration
+also logs an error and needs a page reload. Web SDK keeps a rejected
+configuration, so another configure call on the same instance can't recover
+it.
+
+The helper configures the SDK and updates consent. It doesn't send a page
+view, request offers or render decisions. Keep your own
+[`sendEvent` personalization code](https://experienceleague.adobe.com/en/docs/experience-platform/collection/js/commands/sendevent/personalization)
+behind the same consent condition and vendor switch, and run it after SDK
+configuration. Calls to `alloy` before the helper creates it fail.
+
+Web SDK consent applies to every service on this SDK instance. Use a
+Target-only datastream when you map it to `experience`. If the datastream also
+sends analytics or advertising data, choose a consent condition that covers
+those purposes. Don't share this helper's `window.alloy` installation with a
+separate Adobe Tags or Web SDK initializer.
+
+## 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                                                                                                                                                                                                                                                                                           |
+| ---------------------- | ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `mode`                 | Required                 | `'atjs'` or `'websdk'`. Register one deployment path per page.                                                                                                                                                                                                                                     |
+| `category`             | `'experience'`           | A c15t category or condition. Use a stricter condition if the SDK also serves other purposes.                                                                                                                                                                                                      |
+| `nonce`                | None                     | CSP nonce for the loader. Surrounding whitespace is trimmed. A nonce from the consent provider also reaches the loader.                                                                                                                                                                            |
+| `scriptUrl`            | Required for at.js       | URL of your at.js download. Root-relative URLs work. Surrounding whitespace is trimmed.                                                                                                                                                                                                            |
+| `targetGlobalSettings` | `{ optinEnabled: true }` | at.js settings applied before the file loads. Supported fields are `cookieDomain`, `secureOnly`, `bodyHidingEnabled`, `bodyHiddenStyle`, `pageLoadEnabled`, `viewsEnabled`, `timeout`, `visitorApiTimeout`, `cspScriptNonce` and `cspStyleNonce`. The helper always sets `optinEnabled` to `true`. |
+| `datastreamId`         | Required for Web SDK     | Public ID of the Target-enabled datastream. Surrounding whitespace is trimmed.                                                                                                                                                                                                                     |
+| `orgId`                | Required for Web SDK     | Organization ID including the `@AdobeOrg` suffix. Surrounding whitespace is trimmed.                                                                                                                                                                                                               |
+| `version`              | Required for Web SDK     | Exact stable version of `2.21.0` or later in `https://cdn1.adoberesources.net/alloy/<version>/alloy.min.js`. Surrounding whitespace is trimmed. Older versions, ranges, aliases and prerelease versions log an error and skip the loader.                                                          |
+
+A missing or blank required value logs a configuration error and skips the
+integration. The helper stays listed in the preference dialog. It doesn't check
+whether your IDs, SDK version or self-hosted file exist.
+
+## Loading and revocation
+
+Before the first permitted grant, neither mode creates Adobe globals, requests
+a loader or writes Adobe storage. Rejecting the mapped consent keeps it that
+way. The Adobe Target vendor switch can also block loading inside an allowed
+category.
+
+When several loaders share the same helper options, every registration must
+permit Adobe Target before the shared runtime opts in. An initially denied
+registration counts toward that decision too.
+
+After the first grant, at.js stays installed. On revocation, the helper calls
+the Opt-in service's Target denial API if it's available. A later grant
+approves Target again without downloading or running a second copy of at.js.
+The denial doesn't cancel in-flight requests, remove existing offers, restore
+page content or erase cookies. Without the Opt-in service, only a page reload
+stops the installed runtime.
+
+After its first grant, Web SDK stays installed so the helper can send
+`setConsent` with `value.general: 'out'` on revocation. A later grant sends
+`'in'` again without configuring or downloading the SDK again. If consent is
+withdrawn during the initial download, the load callback doesn't configure the
+SDK or send an `'in'` signal. It can initialize after a later grant.
+
+The helper checks current consent when configuration finishes. It doesn't
+leave an earlier opt-in waiting in Adobe's configuration queue. Once the
+helper hands a command to Adobe, the SDK can still finish that command or an
+in-flight request after revocation. Its consent API doesn't unload listeners
+or restore rendered decisions. Keep c15t's default reload on revocation.
+
+Removing the last c15t registration sends a denial to the installed SDK when
+its consent API is available. It can't unload Adobe's runtime. Reload the page
+before you mount the helper again after its last registration was removed,
+even with the same options. Web SDK allows configuration only once per
+instance. Also reload before you change IDs, versions or deployment mode.
+
+`defaultConsent: 'pending'` is a configuration default, not a replacement for
+c15t's loading gate. Adobe can use consent saved on an earlier page instead.
+The helper resends the permitted state after loading on each page. Web SDK
+persists consent, including an opt-out, in `kndctr_<orgId>_consent`, and its
+consent update can contact Adobe. Adobe replaces `@` with `_` in the
+organization ID when it names the cookie.
+
+If you use [Adobe Analytics](./adobe-analytics.md) to load an
+Adobe Tags property, every rule in that property starts under its configured
+measurement gate. Remove Target and Web SDK rules from that property when you
+use this helper. Registering this helper can't constrain another loader.
+
+## Cookies and storage
+
+Actual storage depends on your Adobe deployment and settings. Adobe documents
+these names:
+
+| Cookie                                            | Purpose                                                                                                                                        |
+| ------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| `mbox`                                            | at.js visitor and session values on your domain. Adobe documents a two-year lifetime from the last login.                                      |
+| `at_check`                                        | Temporary at.js cookie-support test.                                                                                                           |
+| `mboxEdgeCluster`                                 | Edge routing when `overrideMboxEdgeServer` is enabled in the at.js installation.                                                               |
+| `<clientcode>!mboxPC`, `<clientcode>!mboxSession` | Target server cookies on `tt.omtrdc.net` when cross-domain support is enabled. Your site can't delete these HTTP-only third-party cookies.     |
+| `kndctr_<orgId>_consent`                          | Web SDK's persisted consent preference, with `@` replaced by `_` in the organization ID. Web SDK can also create identity and cluster cookies. |
+
+Revocation doesn't delete cookies already written. Check Adobe's
+[Target cookie reference](https://experienceleague.adobe.com/en/docs/core-services/interface/data-collection/cookies/target)
+and the SDK's actual storage in your browser before you configure cleanup.
+
+## Verify Adobe Target
+
+For at.js, filter Network by your self-hosted file URL and by `tt.omtrdc.net`.
+After a grant, check that `targetGlobalSettings.optinEnabled` is `true` and
+that your Target activities load. If you use Adobe Opt-in, check that only its
+Target permission changes when you revoke.
+
+For Web SDK, filter Network by `cdn1.adoberesources.net` and
+`edge.adobedc.net`. Confirm there is no `alloy` global before consent. After a
+grant, check that `alloy.q.push` is no longer the array's native push method.
+The SDK keeps the `alloy` function when it activates, so the function's
+presence alone doesn't prove the SDK loaded. Use a real Target-enabled
+datastream to check offer delivery and server-side consent persistence.
+
+Sources:
+[Target privacy and Opt-in support](https://experienceleague.adobe.com/en/docs/target-dev/developer/implementation/privacy/cmp-privacy-and-general-data-protection-regulation),
+[at.js settings](https://experienceleague.adobe.com/en/docs/target-dev/developer/client-side/at-js-implementation/functions-overview/targetglobalsettings),
+[self-hosting at.js](https://experienceleague.adobe.com/en/docs/target-dev/developer/client-side/at-js-implementation/deploy-at-js/implement-target-without-a-tag-manager),
+[Adobe Opt-in API](https://experienceleague.adobe.com/en/docs/id-service/using/implementation/opt-in-service/api),
+[Web SDK base code](https://experienceleague.adobe.com/en/docs/experience-platform/collection/js/install/base-code),
+[Web SDK library URL](https://experienceleague.adobe.com/en/docs/experience-platform/collection/js/install/library),
+[Web SDK datastream ID and version support](https://experienceleague.adobe.com/en/docs/experience-platform/collection/js/commands/configure/datastreamid),
+[Web SDK default consent](https://experienceleague.adobe.com/en/docs/experience-platform/collection/js/commands/configure/defaultconsent)
+and
+[Web SDK setConsent](https://experienceleague.adobe.com/en/docs/experience-platform/collection/js/commands/setconsent).
+
+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.