@c15t/react 3.2.0-canary.0 → 3.2.0

package/docs/integrations/amazon-ads.md

@@ -0,0 +1,424 @@
+---
+title: Amazon Ads
+description: Load Amazon Ads with c15t after marketing consent and verify its
+  loader, storage and revocation behavior.
+seoTitle: Amazon Ads consent with c15t
+seoDescription: Configure the c15t amazonAdsTag helper, gate vendor requests on
+  marketing consent and understand what happens when consent is withdrawn.
+icon: radar
+group: integrations
+---
+
+The `amazonAdsTag` helper keeps Amazon Ads off the page until `marketing` consent is granted.
+Remove direct snippets and tag manager copies so they cannot bypass c15t.
+
+## Configure Amazon Ads
+
+| 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 { amazonAdsTag } from '@c15t/integrations/amazon-ads';
+
+export const scripts = [amazonAdsTag({ region: 'NA', tagId: 'YOUR_TAG_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).
+
+The c15t `amazonAdsTag` helper loads Amazon's advertising tag after
+`marketing` consent. It creates no Amazon queue or script before that grant.
+When you supply the visitor's country, the helper also loads Amazon Consent
+Signal, ACS, and forwards the current permission for ad storage and user data.
+
+To enable ACS, pass `countryCode` with the actual visitor country from your
+server or another trusted geography source. The helper trims and uppercases
+that value. It never assumes `US`. The `region` option selects your Amazon
+advertising account's region and does not identify the visitor's country.
+
+Amazon's template requires a country code to process ACS data. If the country
+is unknown, omit `countryCode`; c15t then loads only the main tag. Confirm
+which signals your account and traffic require before deploying. Amazon's
+template states that EEA traffic needs at least one of TCF, GPP or ACS.
+Amazon's [consent-signal requirements](https://advertising.amazon.com/en-gb/resources/ad-policy/consent-signal-requirements)
+require a valid consent signal when transmitting personal data from UK and
+EEA users to Amazon Ads.
+
+## Options
+
+| Option               | Default                                             | Behavior                                                                                                                                                                              |
+| -------------------- | --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `tagId`              | Required                                            | Amazon Ads tag ID passed to `amzn('addTag', ...)`. The helper trims it. A missing, empty or whitespace-only value logs an error and loads nothing.                                    |
+| `region`             | `NA`                                                | `NA` or `EU`, passed to `amzn('setRegion', ...)`. Use the region for your advertising account. Amazon's template groups North America, South America, Japan and Australia under `NA`. |
+| `trackPageView`      | `true`                                              | Sends one initial `amzn('trackEvent', 'PageView', ...)`. Set `false` when your application owns the initial page view.                                                                |
+| `pageViewAttributes` | `{}`                                                | Attributes for that initial PageView, such as `value`, `currencyCode` or `clientDedupeId`.                                                                                            |
+| `countryCode`        | None                                                | Actual visitor country, as a two-letter ISO 3166-1 code. Enables the consent helper. Blank values disable ACS.                                                                        |
+| `ipAddress`          | None                                                | Optional visitor IP address passed to ACS. Used only when `countryCode` enables ACS.                                                                                                  |
+| `gpp`                | None                                                | Existing IAB GPP consent string passed to ACS. Used only when `countryCode` enables ACS. The helper does not create or validate this string.                                          |
+| `scriptUrl`          | `https://c.amazon-adsystem.com/aat/amzn.js`         | Main loader URL override. A blank value falls back to the default.                                                                                                                    |
+| `consentScriptUrl`   | `https://c.amazon-adsystem.com/aat/amzn-consent.js` | ACS loader URL override. A blank value falls back to the default.                                                                                                                     |
+
+The returned script uses `marketing` by default. A category override on that
+script also changes the permission forwarded to ACS, including during
+configuration replacement. Both `enableAdStorage`
+and `enableUserData` follow the script's effective permission, including its
+vendor switch. They are not independent configuration flags.
+
+The helper does not set user data for advanced matching or create a TCF
+consent string. Do not manufacture a TCF string to satisfy a tag's consent
+checks. Use your existing IAB consent implementation when Amazon requires
+TCF. Amazon's template says TCF takes priority when several signals are
+present.
+
+## Loading and revocation
+
+Before the script's permission is granted, c15t creates no `window.amzn`,
+`amzn.q` or `amznConsent`, loads neither Amazon library and sets no Amazon
+cookie or browser storage. This guarantee covers the helper's own actions.
+Remove other Amazon loaders to apply the same gate to the whole page.
+
+After grant, the helper preserves an existing `amzn` function or creates
+Amazon's nested command queue. Each entry contains the command arguments and
+a timestamp, `[arguments, Date.now()]`.
+
+When ACS is enabled, the helper inserts `amzn-consent.js` before the main
+`amzn.js` element and uses ordered script execution. The downloads can
+overlap. After the consent helper executes, c15t calls `amznConsent` with the
+real country and both permissions set to `true`. It then queues `setRegion`,
+`addTag` and the optional PageView before the main library executes. Without
+ACS, it queues those commands before inserting the main tag. The helper
+does not add automatic tracking for client-side navigation.
+
+If consent is withdrawn while the consent helper is loading, its completion
+forwards both permissions as `false` and skips initialization. An already
+started helper can still execute after withdrawal. Amazon's helper writes a
+cookie during evaluation, before the first explicit consent update.
+
+If Amazon has not consumed c15t's queued initialization commands, withdrawal
+removes those entries. Amazon can still be waiting to consume the queue after
+the browser reports that `amzn.js` has loaded. The helper preserves commands
+your application queued itself.
+
+Both loaders stay on the page after revocation. When ACS is available, the
+helper calls `amznConsent` with `enableAdStorage: false` and
+`enableUserData: false`. This forwards withdrawal. Amazon documents no
+shutdown or unload command for this tag, and ACS denial does not stop all
+requests from the running runtime. Keep c15t's default reload on revocation
+to stop that runtime. Removing script elements cannot undo executed code,
+requests already sent or cookies already set.
+
+If marketing is allowed again before a reload, the helper reuses both
+loaders and the existing Amazon function. It restores ACS permission without
+repeating a completed initialization or PageView. If withdrawal canceled
+initialization before Amazon consumed the queue, it queues initialization
+once for the new grant. Changes to unrelated consent categories do not
+repeat these calls.
+
+Full loader disposal or configuration replacement detaches that lifecycle's
+load and error listeners. c15t removes its ACS element after the final
+registration using that element releases it, including registrations with
+different options that borrow the same helper.
+c15t leaves externally supplied helper elements in place. A disposed helper's
+late completion cannot initialize the tag or forward an old consent state.
+ACS permission stays granted while at least one active distinct configuration
+with `countryCode` passes its effective consent gate. Releasing or withdrawing
+one configuration does not deny a surviving permitted configuration. Equivalent
+configurations share their lifecycle and combine their registrations' gates.
+Replacing options evaluates the incoming configuration before settling ACS, so
+an unchanged grant does not produce a temporary denial. Removing `countryCode`,
+removing the configuration or withdrawing consent forwards denial when no
+permitted ACS configuration remains. This includes category overrides and
+vendor restrictions.
+Removing an element does not abort code already downloaded or stop a running
+Amazon runtime. Keep the default revocation reload enabled.
+
+If the ACS library fails to load, c15t reports the failure and withholds the
+tag registration and initial PageView. The main library remains a normal
+core script resource with its own load and error events. Reload to retry a
+failed consent-helper download.
+
+Guard every application-owned `amzn` event call with the current permission
+for the category and vendor. The global function still exists after
+revocation, so checking for that function alone does not check consent. If
+you disable `reloadOnConsentRevoked`, queued application events and the
+running Amazon library can still send requests.
+
+## Cookies and storage
+
+The following names come from the downloaded Amazon libraries reviewed on
+21 October 2026. They are source-code findings, not a complete inventory from
+a live browser session. Account configuration, downstream responses and
+browser restrictions can change which cookies appear and how long they last.
+
+| Name                   | Source                                                                                                                                                                                    | Lifetime in the reviewed code  |
+| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------ |
+| `amzn_consent`         | First-party ACS cookie written by `amzn-consent.js`. The library creates denied defaults during evaluation if the cookie is absent. It requests `Path=/`, `SameSite=Strict` and `Secure`. | 28 days                        |
+| `amznAref`             | First-party measurement-token cookie read, updated or removed by `amzn.js`.                                                                                                               | 30-day token lifetime          |
+| `aatToken`             | First-party token cookie managed by `amzn.js`.                                                                                                                                            | Supplied by the token response |
+| `AMZN-NoCookieConsent` | First-party cached no-consent cookie managed by `amzn.js`.                                                                                                                                | Supplied by the token response |
+
+Neither reviewed library references `localStorage` or `sessionStorage`. That
+does not establish which storage downstream Amazon resources use. A reload
+does not delete existing cookies, and your site's JavaScript cannot delete
+cookies on Amazon's domains.
+
+## Verify Amazon Ads
+
+1. Use a private window with an opt-in policy. In DevTools, filter requests
+   by `amazon-adsystem.com`. Before choosing, then after rejecting and
+   reloading, neither Amazon library nor any Amazon event request should
+   appear. Check cookies and browser storage too.
+2. Allow marketing. Without ACS, check for one `amzn.js` load and the initial
+   PageView. With a real `countryCode`, also check that `amzn-consent.js`
+   executes first and ACS contains the supplied country and granted signals.
+3. Change an unrelated consent category. There should be no second loader
+   or initial PageView.
+4. Withdraw marketing. With ACS enabled, check that both signals become
+   denied. After c15t reloads the page, neither Amazon library should load.
+   If reload is disabled, test your application event guards and do not
+   treat ACS denial as proof that all Amazon traffic stopped.
+
+Use your account's tag ID for an acceptance test. A fetched script or a
+syntactically valid UUID does not establish that an advertiser account or
+conversion endpoint accepted the event.
+
+## Sources
+
+* [Amazon's official Google Tag Manager template](https://github.com/amzn/ads-pao-amznjs-gtm-template), including its README, `template.tpl`, loader URLs, queue contract and ACS fields.
+* [Amazon Ads consent signal requirements](https://advertising.amazon.com/resources/ad-policy/consent-signal-requirements).
+* [The live Amazon tag library](https://c.amazon-adsystem.com/aat/amzn.js) and [consent helper](https://c.amazon-adsystem.com/aat/amzn-consent.js), used to check the queue parser, consent updates and storage names.
+* [Amazon Ads product terms](https://advertising.amazon.com/legal/product-terms), which name Amazon Advertising LLC and its affiliates. The legal entity for an account can depend on its agreement and region.
+
+The account-console installation snippet requires an Amazon Ads login. This
+guide follows Amazon's public template and downloaded libraries.
+
+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.