Request and render Display Ads

You render ads yourself, but still run the Web SDK on the page — for targeting and tracking, not rendering. Best for native apps and marketplaces with heavy UI customization. For SDK-rendered ads instead, see Render Display Ads with the Web SDK.

Every field of the request and response is specified in the Ad Request API reference.

Step 1 — Add the Web SDK and read identity

Add the SDK as in the Web SDK Quickstart, then read the IDs it manages so you can pass them into the request (see Web SDK reference → Identity):

Binoban.user().anonymousId(); // → put in user.id
Binoban.user().id();          // → put in user.userId

Step 2 — Request an ad

curl --location '{rtbPath}/api/rtb/ad' \
  --header 'Content-Type: application/json' \
  --data '{
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "adSlotIds": [7, 12],
    "mediaSource": { "type": "APP" },
    "user": { "userId": "phoneNumber or userId", "id": "anonymousId" },
    "timeout": 200
  }'

rtbPath is the host URL from your connection; no authentication is required on this endpoint.

Step 3 — Read the response and render

Each entry in ads[] has a type (BANNERS or NATIVE) and the matching array. A slot with no eligible ad simply won't appear in ads[] — render nothing for it.

• Banner: draw the banner image at width × height.
• Native: lay the assets (image, title, logo/icon, cta) into your own template so it matches the surrounding content.

Hold onto every bidId — every tracking call needs it. See Ad Slots & Formats for the slot/format background.

Step 4 — Send the user to the destination

Two ways, and they differ in who counts the click:

• Via clickUrl (the tracker URL) — the tracker counts the click, then redirects to the destination. Nothing else to do; the click is counted automatically.
• Via the destination directly — targetUrl (banner) or landingUrl (native) — you send the user straight there, but then you must fire the click event yourself so the campaign's click is counted. See Track ad impressions and clicks → Counting clicks.

Track impression, click, and load events

To properly track advertisement events (impression, click, and load), it is strongly recommended to implement the Binoban Web SDK. All ad events should be sent through the SDK for accurate measurement and attribution.

Quickstart: Web SDK Quickstart

Tracking guide: Track ad impressions and clicks.

Use the bidId value returned in the response (banners[].bidId or natives[].bidId).

// Impression event
Binoban.track("ads_impression", {
  bid_id: "550e8400-e29b-41d4-a716-446655440003",
  index: 3,          // optional: position of the ad in the ads array
});

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

The same pattern applies for load events when the ad is successfully rendered. Direct, no-auth tracker endpoints (idempotent per bidId) are also available — see Track ad impressions and clicks → Direct tracker endpoints.

Populating the user object from the Web SDK

If you're integrating Retail Media, ad-request attribution depends on the user object in this request and in the Sponsored Ads request. Map the SDK's identity calls into that object:

SDK call	Request field	Meaning
Binoban.user().anonymousId()	user.id	Device / anonymous identifier
Binoban.user().id()	user.userId	Logged-in user (e.g. a phone number)

Binoban.user().anonymousId(); // → put in user.id
Binoban.user().id();          // → put in user.userId

user.id and/or user.userId (or both) are highly recommended for conversion tracking and accurate attribution. For the full identity API — persistence, anonymous ID overrides, traits — see the Web SDK reference → Identity.