@cherry_ai/react

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

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

Install

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

pnpm add @cherry_ai/react

npm install @cherry_ai/react

Import styles once in your app:

import "@cherry_ai/react/styles.css";

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

Render an ad

import { CherryAd } from "@cherry_ai/react";
import "@cherry_ai/react/styles.css";

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

CherryAd 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 cherry.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 api.cherry (/ack?p=…)
• clickUrl — GET beacon recorded by api.cherry (/track?p=…); navigation goes to ad.url

Optional local analytics via initPixel or CherryProvider:

import { CherryProvider } from "@cherry_ai/react";

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

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

Custom renderers

Most apps only need CherryAd. For a fully custom unit, export CherryClickAd, CherryLeadFormAd, AdSlot, AdDisclosure, and useImpressionTracking / trackClick / submitFeedback.

Development

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

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.