Web (JavaScript)

Full demand eligibility. This SDK runs in a real browser. All four demand tiers serve, and impression, engagement, and click tracking are automatic.

Install

Add the script tag before the closing body tag:

<script src="https://api.adgentek.ai/storage/v1/object/public/sdk/sdk.js"></script>
<script>
  AdgentekAds.init({
    apiKey: 'YOUR_FULL_API_KEY_HERE',
    slotId: 'YOUR_SLOT_ID'
  });
</script>

Add an Ad Placement

The SDK renders into an element it finds by id. It does not create one, and it does not auto-discover slots. Place this exactly where the ad should appear (e.g. after the AI response)

<div id="adgentek-ad"></div>

Request an Ad

Call after each AI response with the conversational context for the turn:

AdgentekAds.init({ apiKey: 'pk_...', slotId: '<slot-uuid>' });

AdgentekAds.requestAd([
  { role: 'user', content: userMessage },
  { role: 'assistant', content: aiResponse }
]);

Verify

DevTools, Network tab: confirm the serve request and its response.
Trigger a commercial-intent turn and confirm the ad renders.
Confirm the impression pixel request fires from the page on render.

Reference

AdgentekAds.init(options) — global configuration

Field	Type	Required	Description
`apiKey`	string	Yes	Publisher key, domain-locked. Sent as Authorization: Bearer
`slotId`	string	Yes	Placement ID from Inventory → Surfaces. Sent as slot_id; drives targeting, floors, reporting
`containerId`	string	No	Default render target id. Defaults to adgentek-ad
`baseUrl`	string	No	Ad server base. Defaults to `https://api.adgentek.ai/functions/v1/mcp-ad-server`. `https://api.adgentek.ai/ad-server/v1` is the same server and is the preferred form — see below

https://api.adgentek.ai/ad-server/v1 is an alias for the default base URL. Both reach the same ad server and behave identically, so you do not need to set baseUrl at all. For new integrations we recommend /ad-server/v1, which matches the click_url and impression_url values the API returns:

AdgentekAds.init({
  apiKey: 'YOUR_PUBLISHER_KEY',
  slotId: 'your-slot-id',
  baseUrl: 'https://api.adgentek.ai/ad-server/v1'
});

AdgentekAds.showAd(messages, options) / requestAd(…) / getAd(…)

Field	Type	Required	Description
`messages`	array	Yes	The user’s message for the turn
`options.containerId`	string	No	Your AI’s response for the turn
`options.sessionId`	string	No	Where to render; auto-discovery when omitted

Methods

Method	Description
`init(options)`	Stores config. Does not render.
`showAd(messages, options)`	Requests and renders the ad into the container.
`requestAd(messages, options)`	Alias for showAd.
`getAd(messages, options)`	Returns ad data without rendering (no container needed).
`trackImpression(ad)`	Fires the impression pixel only. Prefer `fireDeferredTrackers(ad)`, which fires this plus the deferred and partner pixels.
`fireDeferredTrackers(ad, containerElement)`	Fires all pixels for a custom-rendered ad. This is the one to call after rendering via `getAd()` — see Running your own auction.

Markup

<div id="adgentek-ad"></div>

Note: requestAd/showAd return a Promise; getAd is the only path where the container div is optional.

The ad object

Every method that resolves to an ad gives you the server’s response object unchanged — no fields are stripped or renamed. The ones you are most likely to need:

Field	Type	Description
`bid_price`	number	Price for this placement as a CPM in USD — per thousand impressions, not per impression. Use this to include Adgentek in a client-side auction.
`cleared_price_usd`	number	The same value, named for revenue reconciliation.
`impression_url`	string	Fire this when the ad becomes viewable.
`click_url`	string	Navigate through this on click — see below.
`format`, `title`, `content`, `cta`, `image_url`		The creative.

bid_price is always present and is the post-auction clearing price — what the winning bid cleared at, and therefore what you will be credited for. It is not a raw demand-side bid.

Reconcile against cp, not bid_price. bid_price is rounded to 2 decimal places. The cp query parameter on impression_url and click_url carries the same price at full precision, so use bid_price for the auction decision and cp for figures that have to tie out.

Running your own auction

Use getAd() when you want to compare our price against other demand before deciding to render. It returns the ad without rendering anything, so you can read bid_price first:

const ad = await AdgentekAds.getAd(messages);

if (ad && ad.bid_price > yourBestOtherCpm) {
  renderItYourself(ad);                        // your own markup
  AdgentekAds.fireDeferredTrackers(ad);        // ⚠️ required — see below
}

getAd() fires no tracking. You must fire it yourself, or the impression is never recorded and you are not paid for it.showAd() renders the ad and fires its pixels for you. getAd() does neither — that is the point of it, but it means the tracking obligation moves to you. Call fireDeferredTrackers(ad) once the ad is actually on screen.This fails silently: the ad renders correctly, the user sees it, and no impression appears in your reporting. If your dashboard shows requests but few or no impressions, this is the first thing to check.

Clicks are tracked by navigation, not by a method call. Make your clickable element an anchor whose href is ad.click_url:

<a href="{ad.click_url}" target="_blank" rel="noopener">{ad.cta}</a>

The redirect through click_url is what records the click. A <button> with a JavaScript handler records nothing.

Get Started

Concepts

Integrations

Dashboard

Policies

Install

Add an Ad Placement

Request an Ad

Verify

Reference

The ad object

Running your own auction

​Install

​Add an Ad Placement

​Request an Ad

​Verify

​Reference

​The ad object

​Running your own auction

Install

Add an Ad Placement

Request an Ad

Verify

Reference

The ad object

Running your own auction