Ad events

Lookup reference for what the Web SDK emits and calls for retail-media ad slots. For the integration steps, start at Activate Retail Media; for the tracking walkthrough, see Track ad impressions and clicks.

The ads_* events

The SDK's SSP plugin emits this family as a side effect of rendering an ad slot. It only renders Display Ads, so the auto-emitted column below applies to that family alone — for Sponsored Ads, and on any self-rendered slot, you send the same events yourself with Binoban.track(...). The names and properties are identical either way.

Event	Emitted when	Auto-emitted by the SDK
ads_load	The creative finished loading.	No — see the note below. Send it yourself if you need it.
ads_impression	The ad entered the viewport.	Yes — banner and native renderers.
ads_click	The user clicked the ad.	Only when client-side click counting is on — see Who counts the click.
ads_failed	The ad request threw, or the slot had no creative at the requested index.	Yes.
ads_closed	The user dismissed a closable ad.	Yes.

ads_load is not emitted today

The renderers' onLoad handlers are commented out in the Web SDK, so the SDK never fires ads_load on its own. The event and its /win endpoint are fully wired on the receiving side, so a manual Binoban.track("ads_load", …) is counted normally.

ads_impression · ads_click

Property	Type	Value
bid_id	String	The bidId returned for this ad by the Ad Request or Sponsored Ads API. Required — see Events without a bid_id.
index	Number	Position of the item within its slot's response array. The SDK sends the rendered index; single-item templates send 0.
redirectURL	String	ads_click only, optional. Appended to the click tracker so it redirects onward after counting.

Binoban.track("ads_impression", {
  bid_id: "550e8400-e29b-41d4-a716-446655440003",
  index: 3,
});

Binoban.track("ads_click", {
  bid_id: "550e8400-e29b-41d4-a716-446655440003",
  index: 3,
});

ads_load

Property	Type	Value
bid_id	String	As above. Required.

index is accepted on the event but is not forwarded to the /win endpoint.

ads_failed

Property	Type	Value
slodIds	Array[Integer]	The ad slot IDs the failed request covered.
error	String | Error	The thrown error, or no ads for index (index : <i>, length: <n>) when the slot returned fewer creatives than the container asked for.

slodIds, not slotIds

The property name is misspelled in the SDK. It ships that way, so consumers reading raw event payloads must match slodIds exactly.

ads_closed

Property	Type	Value
slot_id	Integer	The ad slot the user dismissed.

Carries no bid_id, so it reaches your event pipeline but never the ad tracker.

Tracker endpoints

Three of the five events resolve to a direct GET on the tracker. Base is {apiHost}/api/tracker/ad, taken from the SDK's own settings. No authentication is required, so a backend can call them instead of going through the SDK.

Event	Endpoint	Query parameters
ads_impression	GET /billing	bidId, index
ads_click	GET /click	bidId, index, redirectURL
ads_load	GET /win	bidId

curl --location '{apiHost}/api/tracker/ad/billing?bidId=5b0d331d-...'
curl --location '{apiHost}/api/tracker/ad/click?bidId=5b0d331d-...&index=3'

Requests are sent with keepalive, so an in-flight call survives the page unloading on a click. ads_failed and ads_closed have no tracker endpoint — they travel only as events.

Idempotent

The tracker counts each impression and click once per bidId. Sending the same event more than once is safe; only the first is counted.

Behavior notes

Events without a bid_id

The tracker plugin drops any ads_* event whose bid_id is missing or empty before making a request. The event still flows to your normal event pipeline, but nothing is counted against the campaign.

index: 0 on impressions

ads_impression appends index only when it is truthy, so index: 0 is omitted from the /billing call — the first item in a slot reports without a position. ads_click uses an explicit null check instead and does send index=0.

Who counts the click

A build-time flag, ADS_COUNT_CLIENT_SIDE_CLICK, decides this for SDK-rendered banners:

Flag	Banner anchor points at	Who counts
off (default)	clickUrl (the tracker URL)	The tracker, server-side on redirect. The SDK does not fire ads_click.
on	targetUrl (the advertiser's destination)	The SDK, by firing ads_click.

On the self-rendered path the same choice is yours to make per link: send the user through clickUrl and the click is counted for you, or send them straight to targetUrl / landing_url and fire ads_click yourself.

Next steps

• Track ad impressions and clicks — the tracking walkthrough.
• Render Display Ads with the Web SDK — the SDK path, where most of these fire for you.
• Web SDK reference → Ads — the ad-slot rendering API.
• Ecommerce semantic events — the conversion events attribution ties back to.