Skip to content

Audience adapters: third-party CDP integration

An adapter contributes namespaced signal fields — `client` adapters run in the browser, `server-proxy` adapters behind `POST /kywi/adapters/:id`.

An adapter is how a CDP, a geo service or your own attribute store gets into audience rules. It is a small typed object with an id, a declared list of field names, and one function; where that function runs is the only structural decision, and side makes it.

side: 'client' | 'server-proxy' | 'push'

Declaring an adapter is the project's job, not the integrator's — the full PullAdapterConfig / PushAdapterConfig shapes are in Signal adapters: feeding the audience builder from code. This page is the wire: what each side means for where collect() runs and what reaches you as an integrator.

Where each side runs

A client adapter's collect() is called in the browser by runClientAdapters, and its result is cached in sessionStorage under kywi_adapter_<id> before anything else happens. There is no TTL and nothing invalidates it: the first call of a tab's session is the only call, so an upstream that changes mid-session will not be re-read until the visitor opens a new tab. Everything the adapter needs — including any key it calls with — is in the page bundle.

A server-proxy adapter's collect() runs on your server, and the same browser runner reaches it over one POST. That is where a credential belongs, and it is also cached under the same sessionStorage key on the way back.

POST/api/v1/kywi/adapters/:adapterIdNo auth

Runs a registered server-proxy adapter's collect() and returns its record. The visitor signals come from the request body; with no body, the signed signals cookie is read instead, and failing that collect() is called with an empty object — so an adapter that ignores signals answers a bare POST.

200
{
  "data": {
    "geoip-stub.country": "US",
    "geoip-stub.region": "campaign"
  }
}
bash
curl -sX POST http://localhost:3000/api/v1/kywi/adapters/geoip-stub \
  -H 'Content-Type: application/json' \
  -d '{"signals":{"utm":{"source":"newsletter"}}}'

The field names are yours to namespace

fields is what the audience rule builder offers as targetable signals. It is not what evaluation reads. A rule's adapter.<something> reference has adapter. stripped and the remainder looked up as a literal key in the merged record collect() returned — so the two have to agree by hand. Both shipped reference adapters prefix every key with their own id, and that convention is worth copying, but nothing enforces it.

Results from several adapters are merged into one flat record, last one wins, so two adapters that emit the same key silently overwrite each other. Prefixing by id makes that impossible.

What a 404 from the proxy means

Three situations return the same body: no adapter with that id, one registered as client, and one registered as push. A client-side adapter must not be reachable through the proxy, and the route will not disclose that a differently-typed one exists. The two built-in reference adapters are also not registered unless your project names them.

the only failure the proxy reportsjson
{"error":{"code":"NOT_FOUND","message":"Adapter not found"}}

Push adapters do not run

side: 'push' type-checks, registers, and is then never called. The registry's push accessor has no caller anywhere in core or the browser runtime, so a push adapter's transform is dead code. There is no ingest endpoint that feeds it.

The route that looks like one — POST /kywi/identity/:visitorId, which takes an adapterId and a data object behind an X-Kywi-Signature HMAC — never consults the registry. It stores the payload verbatim against the visitor, and nothing in core reads that table back into signals. Until that changes, bring third-party attributes in through server-proxy: the shape you return is the shape audiences see. What those rules can combine them with is What each signal can see, and when.