Banner Ad Integration: 3 stages

  1. Banner Configurations: Create and share ad slots.
  2. Auctions for Banners: Work with auction variables, requests and responses
  3. Rendering Banners: render and display the winning banner assets

Banner ads can be used as homepage sliders, featured brands, and carousels.

​
Banner Configurations

Provide a list of pages with unique identifiers for each banner slot.

​
Landing Pages: Homepage or Custom Pages

Create slots for high-traffic homepages or other landing pages.

A slot includes:

  • SlotID: A unique identifier that can contain alphanumeric characters and the following symbols: !"#$%&'()*+,-._/:;<>?@[]^{}~=
  • Name: A descriptive name (e.g. Homepage Slide 1, Above Trending Products ).
  • URL or Deeplink: The URL where the slot is located.
  • Landing Page name: The slot’s corresponding landing page.
  • Image Width and Height, if you require different sizes across devices we support 1 more set of image sizes
SlotIDLanding Page NameURL or DeeplinksWidthHeightAdditional Width (optional)Additional Height (optional)
top-slot-1Homepage Christmashttp://example.com/home100504040
right-slot-2Homepage Christmashttp://example.com/home50200

Use this sample file to bulk upload banner configurations.

Allow vendors to target specific categories and keywords. Define banner slots and share them.

Example:

SlotIDWidthHeightAlternative Width (optional)Alternative Height (optional)
category-bottom100504040

​
Auction Requests for Banners

:::note Storing the resolvedBidId.

The resolvedbidId simplifies event attribution and recording for you and your vendors, similar to auctionID in sponsored listings. It needs to be stored so events can be reported later, either as a cookie or session variable for web applications, or stored as an internal variable for mobile apps. :::

​
Requests Fields

VariableTypeDefinitionRequired/optionalNotes
typestringType of auctionrequiredMust be set as “banners”
slotsintegerMaximum number of auction winnersrequirednumber of winners you would like the auction to return
slotIdstringExternal slot ID provided by the marketplace.requiredFormat: ^[\w!\"#$%&'()_+,\-._/:;<>?@\[\]^\{\}~=\\]\_$
categoryIdstringMarketplace’s category ID for the auction.required only if category bannersDefaults to homepage auction if no category ID provided.
searchQuerystringrequired only if search banners *you can pass both categoryID and searchQuery in the same callExample “blue running shoes”
devicestringTarget device: desktop or mobile.optionalEnum: “desktop” or “mobile.” Defaults to “desktop.”

​
Response Fields

VariableTypeDefinition
resultTypestring”banners”
winners.resolvedBidIdstringA Topsort ID to be used when this item is interacted with (for reporting impressions or clicks)
winners.typestringType of the winning bid. Enum: “product”, “vendor”, “brand”, “url”.
winners.rankintegerThe product’s auction rank indicates its position, with 1 being the winner. In the auction response, the winners array is sorted, and the rank corresponds to the entry’s index.
winners.idstringThe marketplace’s unique ID for the winning entity.
winners.assetarray
winners.asset.urlstringURL source for a banner asset. The asset is served by Topsort’s CDN, contained in asset array

​
Rendering Banners

Set the banner configurations inside the Topsort admin dashboard. Insert the banner in your web app’s DOM or add a component to your mobile app code.

​
Web Apps

For web apps, use the picture element, which will let you provide multiple sources to the client browser. For example, if the asset has 2 sources:

"asset": [
  {
    "url": "https://topsort.cdnprovider.com/lhs-banner-image-for-p_PJbnN-1x.png",
    "mimeType": "image/png",
    "dimensions": {
      "width": 400,
      "height": 100,
    }
  },
  {
    "url": "https://topsort.cdnprovider.com/lhs-banner-image-for-p_PJbnN-2x.png",
    "mimeType": "image/png",
    "dimensions": {
      "width": 800,
      "height": 200,
    }
  }
]

Then you may generate the following HTML:

<picture>
  <source
    width="400"
    srcset="https://topsort.cdnprovider.com/lhs-banner-image-for-p_PJbnN-1x.png 400w, https://topsort.cdnprovider.com/lhs-banner-image-for-p_PJbnN-2x.png 800w"
  >
  <img src="https://topsort.cdnprovider.com/lhs-banner-image-for-p_PJbnN-1x.png" alt="banner">
</picture>

The client’s browser will then choose the most adequate size depending on the user’s device capabilities and only fetch the size that best fits the user’s device.

​
Native iOS (Swift)

We recommend using AlamofireImage to handle download and render options. You may get your client’s device scaling factor by calling and pick the right size.

[UIScreen mainScreen].scale;

​
In Android (Java)

Use Glide library to render and cache images. As with iOS, you will need to check the device’s scaling factor to determine which image to download:

// Get the screen's density scale
final float scale = getResources().getDisplayMetrics().density;
Combining winners and organic resultsCarousels and Swimlanes