Skip to content

Wiring personalization and consent

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.

kywi.config.tsts
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',
  },
})

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.
NameTypeDefaultDescription
clientRuntimebooleanfalse

Load @kywi-software/js on public pages so audiences are re-evaluated in the browser, the self-ID widget mounts, and the transparency bar appears.

requireConsentbooleantrue

Gate every personalization-category cookie behind the visitor’s consent decision. Must agree with KYWI_REQUIRE_CONSENT, and with every other configured site.

consentBanner'layout' | 'host''layout'

Where the cookieConsent module is mounted, for the startup advisory only. 'host' skips the scan.

transparencyNotice{ enabled?: boolean }enabled

The automatic pill and panel showing which audience a page was personalized for. Only an explicit false suppresses it.

selfIdWidget{ styles? }—

Per-element style overrides for the self-identification widget.

personalizationBadge{ styles? }—

Per-element style overrides for the badge module that opens the transparency panel.

adaptersAdapterConfig[][]

Signal adapters registered for this theme — see Signal adapters.

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.

.env — turning Kywi’s gate off, both halvesbash
# alongside personalization: { requireConsent: false } in kywi.config.ts
KYWI_REQUIRE_CONSENT=false

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 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.

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.