How to integrate an ad SDK into a Next.js chatbot

Wiring an ad SDK into a Next.js chatbot is mostly plumbing: install a package, wrap your existing response handler, render one native card. This guide walks through the full integration for Elo's ad SDK, step by step, from a fresh npm install to your first revenue event showing up in the dashboard.

Why this matters

An AI chat app with no monetization is a cost center. Every message round-trips through a model API you're paying for, and unless you charge a subscription, that conversation earns you nothing. Contextual, in-chat advertising is one of the few monetization paths that works even for free-tier users and one-off conversations that never convert to a paid plan.

The technical bar for adding an ad monetization SDK to a Next.js app is lower than most teams assume. You already have a server-side route parsing model output — the matcher call slots into that same function. The work that actually takes time is tuning ad frequency and relevance, not the initial code.

What you'll need

• A working Next.js chatbot (App Router or Pages Router) with a server-side route or Route Handler that talks to OpenAI, Anthropic, or a custom LLM
• Node 18 or later and a package manager (npm, pnpm, or yarn)
• An Elo publisher account and API key, created at elo.ad
• Access to the point in your code where the model's response text is available server-side, before it streams to the client
• 20 to 30 minutes for the initial wire-up, separate from ad-quality tuning afterward
• If your app runs on a custom LLM rather than OpenAI or Anthropic, review the setup for custom LLM chatbots first — the matcher call is identical, but context formatting differs slightly

The steps

1. Install the SDK

Run the install in your Next.js project root with npm install and the Elo package name. This pulls in the client for both server-side matching and the React components used to render ad cards. Do this before touching your chat route — you want the types available while you edit.

Common mistake: installing only in a subdirectory instead of the project root, which breaks imports from client components later.

2. Initialize the SDK with your API key

Add your Elo API key to your environment file, then initialize the SDK once in a shared server module, not inside every route handler. A single initialization avoids redundant network handshakes on every request.

Why it matters: re-initializing per request adds latency to every chat turn. One shared instance keeps the added overhead of ad matching close to zero.

3. Call the matcher inside your existing response handler

Wherever your route currently receives the model's completion — after the OpenAI or Anthropic call resolves, or after your custom model returns — pass that text plus the user's last message into Elo's matcher function. The matcher runs server-side and returns either a matched ad payload or null.

By 2026 most production chat apps stream tokens to the client as they generate, so the matcher call should run against the completed response, not mid-stream, to avoid matching against a partial sentence.

Common mistake: calling the matcher on every single user turn regardless of length. Short acknowledgments rarely warrant an ad and waste a matcher call.

4. Render the native ad card, not a banner

On the client side, the SDK ships a card component designed to sit inline in the message thread, styled to match conversational UI rather than a display banner. Drop it into your message list wherever the matcher returned a non-null payload for that turn.

This is the step that determines whether users tolerate the ad or scroll past it. A card that looks like part of the conversation gets read; a bolted-on banner gets ignored or blocked.

5. Pass real conversation context, not just the last message

Matching quality improves substantially when you pass the last two or three turns of context instead of a single message in isolation. A user asking about carry-on size reads very differently with the prior turn about planning a trip to Lisbon attached.

If you're building on OpenAI's chat completion format, this context is already sitting in your messages array — you're just slicing the last few entries and forwarding them. Teams running conversational ads on GPT-based chat apps generally see better match relevance once they pass this window instead of a single string.

Common mistake: forwarding the entire conversation history on every call. This inflates payload size and does not improve matching past three or four turns of recency.

6. Test in sandbox mode before going live

Elo's dashboard includes a sandbox setting that returns matched ads without logging billable impressions. Run 15 to 20 varied test conversations through your chatbot in sandbox — cover different topics, short and long messages, and a few off-topic queries — and confirm the card renders correctly and doesn't fire on every single turn.

Common mistake: testing only with one obviously ad-relevant conversation and shipping without ever seeing what happens on an ambiguous or unrelated query.

7. Flip to production and watch the event log

Once sandbox output looks right, switch the environment flag to production. The dashboard's event log shows impressions and clicks in near real time, which is the fastest way to catch a broken integration — if you see zero events an hour after launch with active chat traffic, something upstream is misconfigured, not the SDK itself.

Troubleshooting

No ads returned in sandbox, even on relevant queries. Check that your API key environment variable matches the key shown in the dashboard for the correct project — a mismatched key is the most common cause, not a matcher failure.

Ad card renders but breaks streaming layout. The card component expects to sit as a discrete message in your thread array, not injected mid-stream into a single message's text. Append it as its own entry after the assistant's completed response.

Ads fire on nearly every message. Lower match sensitivity in the dashboard settings, or add a client-side check that skips the matcher call for messages under roughly 4-5 words — those rarely carry enough intent signal to match well anyway.

Matches feel off-topic. This almost always traces back to context window size. If you're only passing the current message, go back to step 5 and forward the last two to three turns instead of one.

Revenue not showing in the dashboard after going live. Confirm the environment flag actually flipped from sandbox to production in your initialization code — a leftover sandbox flag will keep generating matches with zero billable events indefinitely.

Card styling clashes with your chat theme. The card ships with default styling meant to be overridden; pass your own CSS classes rather than fighting the defaults with override flags.

Tools and resources

• Elo publisher dashboard and API key setup, at elo.ad
• Guidance for custom LLM chatbots running models outside OpenAI or Anthropic
• Comparison of ad monetization SDKs for AI chatbot developers if you're still evaluating vendors
• Node 18+ runtime and your existing Next.js chat route as the integration point
• The sandbox environment setting in the dashboard, used before any production traffic touches the matcher

What to do next

Once the SDK is live and events are logging correctly, the next lever is ad frequency and revenue tuning rather than more code. Read the breakdown on how to monetize an AI chatbot with conversational ads for how CPM, matching thresholds, and card placement interact once you have real traffic instead of sandbox tests.

FAQ

One last thing

The integration code is the easy part — most of the value you get from an ad SDK in 2026 comes from what you don't do. Skip the matcher call on short, low-intent turns, keep the context window to two or three messages, and resist the urge to raise match frequency past what your sandbox testing showed felt natural. A chatbot that shows one well-matched card per relevant conversation earns more per session than one that fires on every turn and gets ignored.