# Signal adapters: feeding the audience builder from code

URL: https://kywi-docs-production.up.railway.app/developing/signal-adapters-feeding-the-audience-builder-from-code
Type: docPage

An adapter declares the fields a rule can target plus a collect or transform function; client, server-proxy and push adapters differ in who runs it.

An adapter is four properties: an id, a side, the field names it promises, and one function. There are two shapes, and the `side` discriminates them.

export interface PullAdapterConfig { id: string side: 'client' | 'server-proxy' fields: string[] collect: (signals: Partial<VisitorSignals>) => Promise<Record<string, unknown>> } export interface PushAdapterConfig { id: string side: 'push' fields: string[] transform: (payload: unknown) => Record<string, unknown> }

The two adapter shapes, from @kywi-software/core/config. defineAdapter() is an identity helper — it exists so the object is type-checked at the declaration site rather than at the theme.

## fields is a contract, not documentation

Whatever an adapter lists in `fields` becomes targetable in the audience rule builder; at runtime `collect()`'s returned record is merged into the visitor's signals under `adapters`, and a rule reaches it as `adapter.<id>.<key>`. Namespace your keys with the adapter id — both built-ins do, and both derive the prefix from the `id` argument so registering the same adapter twice under different ids keeps the two sets of fields apart.

## Declaring them

Adapters hang off `theme.personalization.adapters`, on the theme like every other personalization setting. `defineAdapter` and both built-ins come from the same `@kywi-software/core/config` import as `defineTheme`.

import { defineTheme, geoipStubAdapter, staticAttributesAdapter } from '@kywi-software/core/config' defineTheme({ name: 'default', regions: [ /* … */ ], personalization: { adapters: [ staticAttributesAdapter({ tier: 'enterprise' }, 'segment'), geoipStubAdapter(), ], }, }) // fields: 'segment.tier', 'geoip-stub.country', 'geoip-stub.region' // audience condition: signal 'adapter.segment.tier' equals 'enterprise'

## kywi.config.ts

Adapters are gathered across *every* theme in the config and de-duplicated by id, first declaration winning, so two themes naming the same adapter register it once rather than twice. An app can also register adapters the config never mentions by passing them to the registry directly — those go in first, so a config adapter cannot shadow one.

## Who runs collect()

`client` adapters run in the browser, inside the `@kywi-software/js` runtime, which means anything they touch is visible to the visitor. `server-proxy` adapters run on the server and are additionally exposed as `POST /api/v1/kywi/adapters/:adapterId` — that is the side to use when the upstream needs a key the browser must not hold. The request/response shape, the 404 cases, and the (missing) auth check are written once, on [Audience adapters: third-party CDP integration](/integrating/audience-adapters-third-party-cdp-integration/).

## The push side has nowhere to arrive

`PushAdapterConfig` type-checks and the registry models it, but no route anywhere accepts a payload to hand to a `transform()` — the only mounted adapter endpoint looks the id up on the pull side. A `side: 'push'` adapter is inert as shipped. If you are feeding data in from a CDP or a warehouse today, do it through a `server-proxy` adapter that fetches, or write the signals from your own route; see [Audience adapters: third-party CDP integration](/integrating/audience-adapters-third-party-cdp-integration/).

## What one looks like inside

Both built-ins are dependency-free reference implementations, and both are `server-proxy`. `geoipStubAdapter` is the shorter of the two and shows the whole contract — deterministic, namespaced, and returning a flat record:

export function geoipStubAdapter(id = 'geoip-stub'): PullAdapterConfig { return { id, side: 'server-proxy', fields: [`${id}.country`, `${id}.region`], collect: async (signals: Partial<VisitorSignals>) => { const hasCampaign = Boolean(signals.utm?.source) return { [`${id}.country`]: 'US', [`${id}.region`]: hasCampaign ? 'campaign' : 'direct', } }, } }

## @kywi-software/core · audiences/adapters/builtin.ts

## Adapters are code, and only code

`collect` and `transform` are functions, so an adapter can never be created from the admin, exported, or round-tripped through the database — and the config validator's theme schema does not model `adapters` at all, so a malformed one is caught by TypeScript or not at all. The audience rules that consume the fields are database rows an editor owns; the adapter that supplies them is a deploy — so removing an adapter and removing the rules that reference its fields are two separate changes in two separate places, and the order matters ([retiring an audience without breaking pages](/targeting/retiring-an-audience-without-breaking-pages/)).
