Skip to content

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

kywi.config.tsts
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:

@kywi-software/core · audiences/adapters/builtin.tsts
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).