Skip to main content
retail media

Render Sponsored Ads with the Web SDK

active
Audience: developerUpdated 2026-08-19

The 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",
},
});

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:

PageField
Search resultskeyword
Category / listingcategoryId
Product detailproductId
Product Listing Pagenone — the slot fills from promotion targeting
Call it after 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.

Use the sponsored attribute, not data-bob-id

Sponsored 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:

FieldWhat it is
type"PRODUCT"
slotIdThe ad slot this filled
bidIdThe tracking key for this placement
campaignIdThe campaign that won
id · sellerId · variantIdCatalog references — the offer that won
productThe 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_impression once the ad becomes visible, and ads_click on interaction.
  • Counts each bidId once 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​