Signal adapters: feeding the audience builder from code
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>
}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'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.
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',
}
},
}
}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).