# Audience adapters: third-party CDP integration

URL: https://kywi-docs-production.up.railway.app/integrating/audience-adapters-third-party-cdp-integration
Type: docPage

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](/developing/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.

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.

curl -sX POST http://localhost:3000/api/v1/kywi/adapters/geoip-stub \ -H 'Content-Type: application/json' \ -d '{"signals":{"utm":{"source":"newsletter"}}}'

## Unauthenticated by design, not by oversight

The route resolves no session, reads no bearer token and applies no role gate — and it has to be that way. `runClientAdapters` calls it with a bare `fetch()` from the visitor's own browser, no credential attached, because the caller is an anonymous page load — gating the route would break every site that collects a signal on one. The route's only real boundary is what a registered `server-proxy` adapter's `collect()` chooses to return. Anyone who can reach the origin can POST any `signals` they like and read that output, so treat it as public: put the upstream credential behind the adapter, never the upstream's answer about someone else.

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

## A field that no key matches fails silently

Declare `fields: ['segment.tier']` and return `{ tier: 'enterprise' }` and you get no type error, no 404 and no log line. The rule builder offers `adapter.segment.tier`, evaluation resolves it to null, and every audience depending on it simply never matches. Check the two against each other when you write the adapter; nothing downstream will.

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 reports

## 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](/targeting/what-each-signal-can-see-and-when/).
