@kili-ai/react

React components for Kili ads: click-through cards and lead-form units, with impression/click tracking, disclosure, and feedback controls.

Pair with @kili-ai/api — fetch ads on the server, render them here.

Install

Peer dependencies: react and react-dom >=18.

pnpm add @kili-ai/react

npm install @kili-ai/react

Import styles once in your app:

import "@kili-ai/react/styles.css";

Override --kili-* custom properties on any ancestor (e.g. :root) to theme the cards.

Render an ad

import { KiliAd } from "@kili-ai/react";
import "@kili-ai/react/styles.css";

export function ResponseAds({ ads }: { ads: Array<{ adText: string; adId?: string; placement: string; placementId: string }> }) {
  return (
    <>
      {ads.map((ad) => (
        <KiliAd
          key={ad.placementId}
          ad={ad}
          sessionId={chatSession.id}
          fallback={null}
        />
      ))}
    </>
  );
}

KiliAd picks the renderer from the ad payload. A lead-form ad without sessionId and apiKey degrades to a click-through card.

Optional adId on each ad is the stable catalog identity from getAds(). Pass it through so impression and click events can be attributed to a specific creative.

| Prop | Type | Description | |------|------|-------------| | ad | Ad \| null \| undefined | Object from kili.getAds(). Renders fallback when empty. | | sessionId | string | Required for lead-form ads and feedback. | | apiKey | string | Required for lead-form ads. Pass from your server, not a client env var. | | feedbackUrl | string | Your backend feedback endpoint. Omit to hide thumbs up/down. | | fallback | ReactNode | Rendered when there is no ad. Keep this cheap. | | onImpression / onClick / onFeedback | callbacks | Optional analytics hooks. Beacons still fire independently. |

Tracking

Impression and click billing uses the server-issued impUrl and clickUrl beacons returned by getAds(). The pixel fires them automatically once an ad is viewable (impression) or clicked — no client-side endpoint configuration required.

• impUrl — GET beacon recorded by server.kili (/ack?p=…)
• clickUrl — GET redirect recorded by server.kili (/track?p=…); navigation goes through clickUrl, which 302s to ad.url with ?pxclid= (PIXEL_CLICK_ID_QUERY_PARAM). The advertiser pixel stores that as klclid (ATTRIBUTION_CLICK_ID_KEY) for CAPI POST /gateway/events.

Exported constants (same values as @kili-ai/api / server.kili):

import {
  PIXEL_CLICK_ID_QUERY_PARAM,
  ATTRIBUTION_CLICK_ID_KEY,
  GATEWAY_EVENTS_PATH,
} from "@kili-ai/react";

Optional local analytics via initPixel or KiliProvider:

import { KiliProvider } from "@kili-ai/react";

<KiliProvider pixelId="my-site" debug onEvent={(e) => console.log(e)}>
  {children}
</KiliProvider>

The deprecated endpoint option (formerly POST /ads/track) is no longer used for billing.

Custom renderers

Most apps only need KiliAd. For a fully custom unit, export KiliClickAd, KiliLeadFormAd, AdSlot, AdDisclosure, and useImpressionTracking / trackClick / submitFeedback.

Development

Run from this repo (pkg.react.kili):

pnpm install
pnpm check
pnpm test
pnpm build

Releasing

Changesets live in this repo only. Until 1.0.0: patch = fix, minor = feature or breaking, major = 1.0.0.

pnpm changeset              # add a changeset on a feature branch
pnpm changeset:status       # preview the bump

On merge to main, CI opens a chore: update version PR (pnpm changeset:version). Merging that PR publishes to npm (pnpm changeset:publish), tags vX.Y.Z, and creates a GitHub Release. Set the GitHub Actions secret NPM_TOKEN.