Overview

One call on your server, one component in your UI. Adzen does the matching; you keep the experience.

The @adzenai/ai SDK is the fastest way to put Adzen into an assistant built on plain React or Next.js. You pass it the message a user sent. It returns the single ad that genuinely fits that turn — or nothing, when nothing does — and tracks the impression once your user can actually see it.

No CopilotKit or AG-UI required. If you are building on CopilotKit agents, the CopilotKit integration is the faster path.

How it works

The flow is two steps:

1. Fetch a placement on the server with fetchAdzenAd(...). Your API key stays server-side.
2. Render the returned placement on the client — either with the built-in <AdzenCard> or your own markup via useAdImpressions.

Where each piece runs

┌────────────────────────────────────────────┐
│  Your React / Next.js UI                   │
│  ┌───────────────────────────────────────┐ │
│  │  Content (message, article, …)        │ │
│  └───────────────────────────────────────┘ │
│  ┌───────────────────────────────────────┐ │
│  │  <AdzenCard ad={placement} />         │ │
│  └───────────────────────────────────────┘ │
└───────────────▲────────────────────────────┘
                │  AdzenPlacement (JSON)
┌───────────────┴───────────────────────────────┐
│  Your server (route handler / server action)  │
│  fetchAdzenAd({ apiKey, content, messageId }) │
└───────────────▲───────────────────────────────┘
                │  POST /process  (X-API-Key)
┌───────────────┴───────────────────────────────┐
│  Adzen API                                    │
└───────────────────────────────────────────────┘

Adzen can never break your product. fetchAdzenAd returns null (never throws) on no-match, timeout, or error, and <AdzenCard> renders nothing when there is no ad — so your UI is unaffected when there’s no placement.

An empty response is a feature. It means nothing cleared our relevance and brand-safety bar for that turn, and we declined to fill the slot rather than show your users something that does not belong there.

Before you start

1. Get an Adzen API key from your Adzen account representative.
2. Have a React >=18 app with somewhere to run server code (a Next.js route handler / server action, or any Node >=18 backend).

What the code looks like

Server — fetch a placement (key stays server-side):

// app/api/ad/route.ts (Next.js App Router)
import { fetchAdzenAd } from "@adzenai/ai";
 
export async function POST(req: Request) {
  const { content } = await req.json();
  const placement = await fetchAdzenAd({
    apiKey: process.env.ADZEN_API_KEY!,
    content,
    messageId: crypto.randomUUID(),
  });
  return Response.json({ placement });
}

Client — render the placement:

"use client";
import { AdzenCard } from "@adzenai/ai/react";
 
// `placement` is what your route returned (null when there's no match).
// AdzenCard's `ad` prop doesn't accept null, so render it only when there is one.
{placement && <AdzenCard ad={placement} />}

Choose your path

What your users see

• Your content renders normally with zero dependency on the ad request.
• A sponsored placement appears where you render <AdzenCard> (or your own markup) when Adzen returns a match.
• A render impression fires when the ad mounts; a view impression fires once it has been visible for the viewability threshold.
• Click-through links open the advertiser destination.

Next

1. Quick start — your first matched ad.
2. Integration walkthrough — custom rendering and verification.
3. Configuration — tune fetching, viewability, and impressions.