@c15t/scripts 3.0.0-alpha.1 → 3.0.0-alpha.3

package/docs/integrations/granular-consent.md

@@ -1,208 +0,0 @@
----
-title: Granular consent
-description: Let visitors grant a category and still turn one vendor off,
-  without adopting IAB TCF.
-group: integrations
----
-
-Granular consent is choice below the category level: a visitor grants
-marketing and still turns Meta off. The unit of that choice is a vendor, so
-the API names them `vendors`, `vendor` and `data-vendor`, and the hooks
-`useVendorAllowed` and `useVendorDraft`. Everything else stays as it is:
-categories, policies, and the preference center gain vendor rows rather than
-a second consent model.
-
-## Declare vendors
-
-Add `vendors` to your runtime options. Each vendor sits inside a category
-condition and needs a name and a privacy policy URL so the preference surface
-can list it. The React provider takes the same option once its preference
-center renders vendor rows; scripts, rules and iframes are gated the same way
-whichever place declares it:
-
-```ts
-import { hosted, type Vendor } from 'c15t';
-import { createConsentRuntime } from 'c15t/runtime';
-
-const vendors = [
-	{
-		id: 'meta-pixel',
-		name: 'Meta Pixel',
-		category: 'marketing',
-		privacyPolicyUrl: 'https://www.facebook.com/privacy/policy/',
-		description: 'Ad conversion measurement and audiences.',
-	},
-	{
-		id: 'google-analytics',
-		name: 'Google Analytics',
-		category: 'measurement',
-		privacyPolicyUrl: 'https://policies.google.com/privacy',
-	},
-] satisfies Vendor[];
-
-const runtime = createConsentRuntime({
-	mode: hosted({ url: '/api/c15t' }),
-	vendors,
-	scripts: [
-		{
-			id: 'meta-pixel',
-			category: 'marketing',
-			vendor: 'meta-pixel',
-			src: 'https://connect.facebook.net/en_US/fbevents.js',
-		},
-	],
-});
-
-// Start in the browser after mount. The endpoint must serve your c15t backend.
-runtime.start();
-```
-
-The `id` is a lowercase slug of up to 64 characters. Reuse it as the `vendor`
-field on scripts and network rules and as the `data-vendor` attribute on
-iframes. Integrations from `@c15t/scripts` already set `vendor` to their
-manifest slug, so `gtag()` and `metaPixel()` need no extra wiring.
-
-A backend can also declare vendors. Add `vendors` and an optional
-`vendorListVersion` to the manifest configuration; `/init` returns them and the
-client merges them with the vendors declared in code. When both declare the
-same id, the copy declared in code wins, and the backend copy comes back if the
-code declaration is removed later. A slug used by a script, rule or iframe
-but declared nowhere still gates loading. It is hidden from the preference surface, and the
-runtime warns about it outside production.
-
-## How a vendor is gated
-
-A target loads when its category condition passes and the visitor has not
-turned its vendor off:
-
-```text
-loads  =  category condition satisfied  AND  vendor not denied
-```
-
-The category is evaluated first, so an unknown category still throws as a
-configuration error. A vendor toggle never grants a category on its own: with
-marketing denied, `meta-pixel` stays blocked whatever its own switch says.
-A script with `alwaysLoad` still mounts, as it does for a denied category;
-its callbacks receive the vendor result in `info.vendor.granted` so a
-self-managing SDK can honor it.
-
-Under an `iab` policy the `vendor` slug is inert. Vendor consent then comes from
-the TC string through `vendorId`, and the vendor rows are not shown.
-
-The same rule applies to the three gates:
-
-| Surface         | Field                           |
-| --------------- | ------------------------------- |
-| Script loader   | `Script.vendor`                 |
-| Network blocker | `NetworkBlockerRule.vendor`     |
-| Iframe blocker  | `data-vendor` on the `<iframe>` |
-
-An iframe with `data-vendor` and no `data-category` is gated on the vendor
-alone. An unknown `data-vendor` value is granted rather than thrown: a vendor
-the visitor never saw cannot have been turned off. Such a frame has no
-category to follow, so a denial the visitor recorded earlier holds even while
-nothing declares the slug, for example before the backend's vendor list has
-arrived on a cold start.
-
-A script, rule or frame keeps its slug declared for as long as it is
-configured. If a backend list or a provider update drops the entry, the
-loader or blocker puts it back, so a stored denial keeps gating it. A slug
-several modules share stays under every category they name it with, whichever
-module updates last, and drops a category only once no module names it there.
-Disposing a loader or blocker, or removing a gated frame from the page, drops
-what only it named, so a vendor no live module owns stops being toggleable.
-
-## Record a vendor choice
-
-Vendor grants travel with the save. Stage them and confirm with the next save,
-or pass them next to the categories:
-
-```ts
-// Stage from a toggle handler; nothing changes until save({}) runs. The
-// empty patch confirms no category, so only the staged vendor is recorded;
-// save() with no input would reconfirm every displayed category too.
-runtime.stageVendorConsent('meta-pixel', false);
-await runtime.kernel.commands.save({});
-
-// Or confirm categories and vendors in one action.
-await runtime.kernel.commands.save({
-	marketing: true,
-	measurement: true,
-	vendors: { 'meta-pixel': false },
-});
-```
-
-`stageVendorConsent` stages a vendor slug for the next save; it is not the
-IAB handle's `setVendorConsent`, which sets a TCF vendor by numeric id and
-takes effect at once. The grants can also travel in the save context as
-`{ vendors }`, which wins when both are given.
-
-Only the vendors the visitor turned off are stored. Accept all and reject all
-both clear that list, so vendors follow their category on a bulk action. A bulk
-action narrowed to the displayed categories only lifts the denials of vendors
-those categories decide on their own; a vendor another granted category would
-still load keeps its denial. A
-vendor that is not declared, or is declared with `disabled: true`, is ignored.
-Under an opt-out policy every vendor starts on and the stored list is the
-do-not-sell list.
-
-A vendor-only change records without touching category receipts. The kernel
-emits `vendors:recorded` rather than `choice:recorded`, writes the
-`<storageKey>-vendors` cookie and localStorage entry, and sends the complete
-grant map to the backend as `vendorChoice`. Category confirmation times are not
-renewed. The vendor entry also carries the subject id, so a visitor whose first
-act only decided vendors keeps the same subject after a reload even though no
-category record exists yet.
-
-Scripts see the vendor result in their callbacks. `ScriptCallbackInfo.vendor`
-carries `{ id, granted }` outside IAB mode. Integrations that send Google
-Consent Mode or RudderStack signals send every category as denied while their
-vendor is off, so the vendor's own consent API cannot re-enable tracking.
-
-## Show vendors in the preference center
-
-The `ConsentWidget` and `ConsentDialog` in React, Vue and Svelte list vendors
-under their category when the provider declares them. Pass the same `vendors`
-array to `ConsentProvider`, to the `vendors` prop of `ConsentRoot` in
-[Next.js](../frameworks/next/script-loader.md#granular-consent) and
-[TanStack Start](https://c15t.com/docs/frameworks/tanstack-start/quickstart#granular-consent),
-to the Nuxt module or Vue plugin config next to `scripts`, or to
-`ConsentManagerProvider` options in Svelte:
-
-```tsx
-import { ConsentProvider, hosted } from 'c15t/react';
-
-<ConsentProvider options={{ mode: hosted({ url: '/api/c15t' }), vendors }}>
-	{children}
-</ConsentProvider>;
-```
-
-Each category row expands to one card per vendor with its own switch. The
-switches disable while the category is off in the draft, and Save records the
-vendors the visitor moved. A custom control uses `useVendorDraft()` from
-`c15t/react` to read and stage the same grants, with `isStale` and `reset` for
-a draft the policy or vendor list changed under, and `useVendorAllowed(id)` to
-read one vendor's effective result. Copy comes from
-`consentManagerDialog.vendors.{title, privacyPolicy, disabledByCategory,
-switchLabel}` in the translations. In Vue, `useConsentDraft()` returns the
-same `vendors` map and `setVendor`; in Svelte, `getConsentManager()` exposes
-`selectedVendors`, `setSelectedVendor` and `getDisplayedVendors(category)`.
-The three frameworks render the same cards, and the parity suite compares
-their markup, accessibility tree, computed styles and geometry.
-
-## What a denial does not do
-
-Turning a vendor off blocks future loads and requests. It does not delete the
-cookies that vendor already set, and
-[clear on revocation](./clear-on-revocation.md) does not help here:
-it runs when a category is denied, and the category stays granted when only one
-of its vendors is off. Remove that vendor's cookies yourself from an
-`onConsentChange` callback that checks `info.vendor.granted`.
-
-A vendor denial has no expiry and no policy basis. It stays until the visitor
-changes it or a bulk action clears it, including across a policy change that
-requires the category choice again.
-
-Adding a vendor to the list does not reopen consent. New vendors default to on
-inside a granted category. Use the policy rule's `copyRevision` when a new
-vendor should prompt the visitor again.