Configuration

Sensible defaults, three places to tune.

The SDK has three configurable surfaces: the server-side fetchAdzenAd call, the <AdzenCard> component, and the useAdImpressions hook. There is no automatic environment-variable binding — your application reads environment variables and passes them in.

Environment variables

These are recommended names. Your server code reads them and passes them to fetchAdzenAd.

Required

Optional

Example .env

ADZEN_API_KEY=your_api_key
ADZEN_LOCATION=US-CA-803

fetchAdzenAd options

fetchAdzenAd(options: FetchAdzenAdOptions): Promise<AdzenPlacement | null> — from @adzenai/ai. Server-side (it sends the API key).

const placement = await fetchAdzenAd({
  apiKey: process.env.ADZEN_API_KEY!,
  content: assistantMessage,
  messageId: msg.id,
  location: process.env.ADZEN_LOCATION,
});

AdzenCardProps

<AdzenCard> from @adzenai/ai/react. Props are dual-mode — supply either a resolved ad (generic usage) or a messageId (CopilotKit event-driven usage), not both.

{placement && (
  <AdzenCard ad={placement} viewabilityThresholdMs={2000} className="my-ad-card" />
)}

The built-in card shows the advertiser avatar (from advertiser_image_url, falling back to the advertiser’s initial), the advertiser name, a “Relevant Ad” disclosure, the headline, and the CTA link (target="_blank", rel="noopener sponsored"). It does not render description — that field is available on the placement for custom rendering.

useAdImpressions

useAdImpressions(ad, options?) => { ref } from @adzenai/ai/react. For rendering your own markup while keeping Adzen impression tracking.

const { ref } = useAdImpressions(placement, {
  adUnitPosition: "chin",
  viewabilityThresholdMs: 1000,
});
// attach ref to the element that represents the ad

Returns { ref } — attach it to your ad element. The render beacon fires once when the ad becomes available; the view beacon fires once the element has been continuously visible for the threshold. Both beacons are skipped when their impression URL is null. AdzenCard uses this hook internally.

Adzen API response format

The Adzen /process API returns:

{
  "message_id": "msg_abc123",
  "ads": [
    {
      "ad_id": 1071,
      "title": "Local Coffee Co",
      "cta": "Learn More",
      "click_through_url": "https://api.adzen.ai/…/redirect/abc1234",
      "advertiser_name": "Acme Corp",
      "sponsor_logo_url": "https://example.com/logo.png",
      "creative_url": "https://example.com/banner.jpg",
      "description": "A great product",
      "placement": "chin",
      "render_impression_url": "https://api.adzen.ai/…/impressions/render",
      "view_impression_url": "https://api.adzen.ai/…/impressions/view"
    }
  ]
}

fetchAdzenAd returns the first ad mapped to AdzenPlacement:

Impression beacons

Both the built-in card and useAdImpressions fire impression beacons as client-side GET requests directly to the delivery API — no server proxy or auth headers required. The impression URLs are pre-built by the API and fired as-is.

• Render impression — fired on mount, as a GET to render_impression_url.
• View impression — fired after the viewability threshold is met, as a GET to view_impression_url.

If render_impression_url or view_impression_url is null, that beacon is skipped. A beacon that fails is retried once after 1 second, then dropped silently.

Viewability

Viewability uses IntersectionObserver via @adzenai/core’s observeViewability():

Error handling and silent degradation

Adzen never throws into your render tree. All failures are silent:

Next

• Integration walkthrough — end-to-end wiring, custom rendering, verification
• How it works — architecture and full API reference
• Quick start — your first matched ad