Render Sponsored Ads with the Web SDK
activeThe SDK path for Sponsored Ads. You tell the SDK what the visitor is looking at — a product, a category, or a search term — and it requests the ads, renders what it can, and tracks impressions and clicks.
Unlike Display Ads, Sponsored Ads are context-bound: the SDK cannot discover a search keyword or a product ID from the page, so this path starts with an explicit call rather than a container the SDK finds on its own.
Best when you want Binoban to own ad rendering and measurement. If your product card is deeply tied to your own design system or data layer, use the API path instead — or use this path's data mode, below, which keeps the SDK's measurement while you keep your markup.
Before you start, complete the shared Retail Media setup: define your media property, your ad slots (choose the Sponsored Ads category), get your connection, credentials & host URLs, and sync your catalog. Sponsored Ads promote real products, so the catalog is required.
Step 1 — Add the Web SDK
Paste the bootstrap snippet into the <head> of your site — full reference:
Web SDK Quickstart. The only part you edit is
the load() call:
Binoban.load({
credentials: {
apiKey: "PROJECT_API_KEY",
sourceIdentifier: "PROJECT_SOURCE_IDENTIFIER",
},
host: {
rtbPath: "YOUR_BINOBAN_SERVER_RTB_URL",
sdkPath: "YOUR_BINOBAN_SERVER_SDK_URL",
apiPath: "YOUR_BINOBAN_SERVER_API_URL",
},
});
Step 2 — Identify the user (optional, recommended)
Anonymous visitors are fine — the SDK assigns an anonymousId on load. If you know who the
user is, call identify for more precise targeting and attribution:
Binoban.identify("jdUserId", { name: "John Doe", email: "jdoe@example.com" });
See Web SDK reference → Identity.
Step 3 — Request the ads
Call sponsoredAds() when you know the page context — after the search resolves, on the
product detail page, on the category page:
await Binoban.ready();
const { rendered, placements } = await Binoban.sponsoredAds({
slotIds: [41, 42],
keyword: new URLSearchParams(location.search).get("q"),
});
Send one context field, matching the slot's Context:
| Page | Field |
|---|---|
| Search results | keyword |
| Category / listing | categoryId |
| Product detail | productId |
| Product Listing Page | none — the slot fills from promotion targeting |
ready()sponsoredAds() resolves with data, and the pre-init queue can only hold calls, not
return values. A call made before the SDK finishes loading still queues and still executes —
enough for rendering — but you will not receive the placements. Await
ready() when you need them.
The call never throws and never rejects — it runs inside your render path, so failures come
back as { rendered: [], placements: [], error } instead.
Step 4 — Choose a mode
The SDK gives you two ways to get ads onto the page. They are not alternatives to pick once and forever: a single call can render a sponsored rail and hand back placements for your own grid.
Mode A — the SDK renders
Put a container where you want ads. data-bob-sponsored-id is the ad slot ID of a
Sponsored Ads slot from Define ad slots:
<div data-bob-sponsored-id="42"></div>
That is the whole integration. When sponsoredAds() resolves, the SDK fills every matching
container and reports the slot IDs it painted in rendered. Impressions and clicks fire
automatically.
data-bob-idSponsored slots use their own attribute. data-bob-id belongs to
Display Ads, whose scan sweeps every such container into
its own ad request and hides the ones that request does not fill. A sponsored slot marked
data-bob-id would be hidden before it could be painted — and an ad inside a hidden box
never records an impression. Never put both attributes on one element.
Mode B — you render, the SDK measures
Declare no container, and render from placements instead. Every product carries the catalog
data you need plus a bind() handle that wires up measurement:
const { placements } = await Binoban.sponsoredAds({ slotIds: [42], keyword });
placements
.filter((p) => p.type === "PRODUCT")
.forEach((placement) => {
const card = renderYourProductCard(placement.product);
grid.prepend(card); // insert first…
placement.bind(card); // …then bind — a detached node never becomes visible
});
bind(el) returns an unbind function. In React it doubles as an effect cleanup:
function SponsoredCard({ placement }) {
const ref = useRef(null);
useEffect(() => placement.bind(ref.current), [placement]);
return (
<div ref={ref}>
<ProductCard product={placement.product} badge="Sponsored" />
</div>
);
}
A BRAND placement is a labelled group — render brand however you like, then bind each
of its products individually:
placements
.filter((p) => p.type === "BRAND")
.forEach((brandAd) => {
renderBrandHeader(brandAd.brand);
brandAd.products.forEach((p) => {
const card = renderYourProductCard(p.product);
rail.append(card);
p.bind(card);
});
});
What comes back
{
rendered: [41], // slot IDs the SDK painted itself
placements: [ … ], // PRODUCT and BRAND items, each bindable
}
rendered and placements describe different things and can both be populated by one call.
The two sponsored display subtypes are rendered by the SDK and reported in rendered;
they never appear in placements.
A PRODUCT placement:
| Field | What it is |
|---|---|
type | "PRODUCT" |
slotId | The ad slot this filled |
bidId | The tracking key for this placement |
campaignId | The campaign that won |
id · sellerId · variantId | Catalog references — the offer that won |
product | The product itself: name, image, landingUrl, price, discountedPrice, currency, brand, plus your catalog attributes |
bind(el) | Wires measurement to your node; returns an unbind function |
A BRAND placement carries type, slotId, brand, and products — an array of the
PRODUCT shape above. It has no bidId and no bind() of its own: the brand block is
not separately billable, only the products inside it are.
What the SDK does automatically
On both modes:
- Fires
ads_impressiononce the ad becomes visible, andads_clickon interaction. - Counts each
bidIdonce per call, whichever mode surfaced it. A product that is both SDK-rendered and bound to your own node still bills a single impression. - Hides a container whose slot came back unfilled, and clears that state on the next call.
You write no tracking calls on either mode — see Track ad impressions and clicks for the event reference.
In Mode B the SDK observes the click but does not navigate: your card's own <a href>
behaves exactly as it would without Binoban on the page.
Repeat calls
Call sponsoredAds() again whenever the context changes — a new search term, a filter, a
route change in a single-page app. Each call is independent: containers are reset and
repainted, and the impression count starts fresh so the new auction's placements bill
correctly.
Step 5 — Customize how the ads look (optional)
The built-in product card is deliberately plain, because a product card belongs to your
store's design. To replace it, register a product template — the same mechanism Display Ads
uses:
<div data-bob-sponsored-id="42">
<template data-bob-template>
<article class="promo">
<span class="promo__badge">Sponsored</span>
<img data-bob-src="image" alt="" />
<h3 data-bob-text="name"></h3>
<p data-bob-text="discountedPrice"></p>
</article>
</template>
</div>
Prices are the raw numbers from your catalog — the SDK does not format currency, because your store already knows its own conventions. Use a JavaScript renderer when you need formatting.
See Web SDK Ad Customization for the full template reference, including every product field you can bind to.
Next steps
- Prefer to call the API from your backend? — Request and render Sponsored Ads.
- Understand the events — Track ad impressions and clicks.
- Look up slot contexts and subtypes — Ad Slots & Formats.