# Wiring personalization and consent

URL: https://kywi-docs-production.up.railway.app/developing/wiring-personalization-and-consent
Type: docPage

Personalization, transparency and the consent gate are theme settings, not site settings — and the consent flag must match an env var or the boot fails.

Every switch on this page lives under `theme.personalization`. A site entry names a theme; the flags are resolved from the *active* site's theme on each request, so two sites sharing a theme share one personalization posture — and a request whose Host matched no site falls back to the first configured site's theme, then to the first theme in the array.

defineTheme({ name: 'default', regions: [ { name: 'header', label: 'Header' }, { name: 'main', label: 'Main Content' }, { name: 'footer', label: 'Footer' }, ], tokens: { /* … */ }, // Load the @kywi-software/js browser runtime on public pages: client // re-evaluation, DOM patching, the transparency panel, the self-ID widget // and the consent banner's behaviour. Server-side audience eval + render // happen regardless of this flag. personalization: { clientRuntime: true, // The consent banner is mounted in components/site-shell.tsx (the theme shell), not // placed as a layout module — tell core so it skips the advisory scan // that otherwise warns on every boot. consentBanner: 'host', }, })

## kywi.config.ts

## The personalization block

The seven settings under theme.personalization. clientRuntime defaults to false and requireConsent defaults to true, and neither default is arbitrary: server-side audience evaluation and rendering happen whatever clientRuntime says, and a consent gate that defaulted to off would be a privacy decision taken by omission.

## What clientRuntime actually gates

Only the browser half. Audiences are evaluated and the page is rendered server-side whether or not the runtime loads; `clientRuntime` decides whether the served page also mounts `@kywi-software/js` to re-evaluate with behavioural and self-ID signals, patch the DOM, and draw the self-ID widget. Leaving it off does not turn personalization off — it turns off everything that can only happen after the first paint.

## requireConsent has an env twin, and they must agree

Next.js edge middleware cannot read `kywi.config.ts`, so the flag is mirrored as `KYWI_REQUIRE_CONSENT`. The mirror is read strictly: anything but the literal string `false` counts as true, so an unset var means the gate is on. Set both halves or neither — while they disagree, the middleware writes a visitor cookie the API then declines to read, and nothing anywhere says so.

# alongside personalization: { requireConsent: false } in kywi.config.ts KYWI_REQUIRE_CONSENT=false

## .env — turning Kywi’s gate off, both halves

## Two startup checks, both throws, both fail the deploy

The API handler first requires every configured site's theme to agree on `requireConsent` — a single process-wide env var cannot carry one answer per site, and letting a second site inherit the first one's privacy default silently is the failure this replaced. It then requires the agreed value to match the env var. Neither is a warning. See [Consent policy: the startup throw and the env mirror](/operating/consent-policy-the-startup-throw-and-the-env-mirror/) for the message shapes and the fix in production.

## The gate applies on read, not only on write

`kywi_visitor` is a personalization cookie, so a request without consent neither writes nor *reads* it. A visitor who accepted last month and has since rejected still has one in the jar; honouring it would re-identify them under the identity they just revoked. Instead that request gets a throwaway id, freshly minted and different on the next request — which is also why an unconsented visitor does not stick to one experiment arm. [What consent does to your targeting](/targeting/what-consent-does-to-your-targeting/) covers what that costs a page.

## consentBanner is an advisory flag, not a placement

Setting it does not mount anything. Core runs a once-per-boot advisory that looks for the `cookieConsent` module in stored page layouts and section templates, and warns when consent is required but nothing can grant it. A banner rendered by the app shell — a theme's `templates.shell`, say — is invisible to that scan, so without `consentBanner: 'host'` a correctly-configured site gets the warning on every boot. See [the no-consent-banner startup warning](/operating/the-no-consent-banner-startup-warning-and-its-false-positive/).

## Transparency is on until you say otherwise

`transparencyNotice` unset means enabled. Only an explicit `enabled: false` stops the pill and panel appearing on their own, and even then a `personalizationBadge` module placed on a page still opens the panel deliberately — turning the notice off removes the automatic surface, not the ability to show it. What the panel exposes is the [site admin's subject](/targeting/the-transparency-panel-and-audience-switcher/).
