With the release of Topsort API V2, banner ads run faster and include more vital information that allows them to be displayed on multiple site pages and devices in different sizes. Check out our API reference for it here.

Banner ads v2 follow the same changes and request format as Topsort API V2. Their only difference is that they have 3 new variable fields. Here is a table of the 3 additional variable definitions for banner ad API V2 requests.

Field

Type

Definition

Required/optional

Notes

categoryId

string

The marketplace's ID of the category for which an auction will be run.

Required for category banners

If no category ID was provided in the request, the banner ad will be default participating in the homepage auction.

device

string

The device for which the ads are meant for: desktop or mobile

Optional

Enum: "desktop" or "mobile." By default, "desktop" is used.

aspectRatio

string

The aspect ratio for a specific slot for a banner placement in the marketplace app.

Required

Format: ^\d+:\d+$
The aspect ratio for the category page must have been previously set up in the Topsort app.

Request

This is an example of the banner ad type auction included in an API V2 request in JSON format.

{
  "auctions": [
    {
      "type": "banners",
      "slots": 1,
      "aspectRatio": "4:1",
      "device”: “mobile”,
      "category": {
        "id": "c_yogurt"
      }
    }
  ]
}

Response

Your response will include as many auction results as you created auction items for (5 being the greatest amount). In the array, winning products are ordered from highest to lowest bid. It will be empty if there were no qualifying bids or if there was an error.

There is a new boolean variable, error, that indicates whether the auction was resolved successfully.

Banner Ad Specific Variable Definitions

There are 2 required variables when implementing banner ads with API V2: resolvedbidId and url.

The variable resolvedbidId simplifies the way we attribute impressions and record certain events for you and your vendors (it replaces the productid and auctionid in API V1). In API V2, productId is no longer required at all to record clicks and impressions. With just resolvedBid returned, you have one less field to reference for the events API calls.

📘

Storing the resolvedbidid

resolvedbidId 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.

FieldTypeDefintion
resolvedBidIdstringAn opaque Topsort ID to be used when this item is interacted with.

url is a URL source for a banner asset. The asset is served by Topsort's CDN. This variable is contained in the asset array. Think of it as a list of URLs that link you to the winning vendor's creative.

FieldTypeDefinition
assetarray of objectsThe list of URL sources for a banner ad asset.
urlstringThe vendor's provided asset that the marketplace will use for the banner ad.

This is an example of the response using the API V2 in JSON format.

{
  "results": [
    {
      "winners": [
        {
          "rank": 1,
          "winnerType": "product",
          "winnerId": "p_PJbnN",
          "resolvedBidId": "WyJlX1BKYm5OIiwiMTJhNTU4MjgtOGVhZC00Mjk5LTgzMjctY2ViYjAwMmEwZmE4IiwiYmFubmVyQWRzIiwiZGVmYXVsdCIsIiJd",
          "asset": [
            {
              "url": "https://topsort.cdnprovider.com/lhs-banner-image-for-p_PJbnN-1x.png"
            }
          ]
        }
      ],
      "error": false
    }
  ]
}

Rendering the Banner in your App

First, set the banner configurations inside the marketplace admin dashboard. Using the response data, you should be able to insert the banner in the DOM of your web app or add a component to you mobile app code.

In 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.

In Native iOS (Swift)

You may get your client's device scaling factor by calling:

[UIScreen mainScreen].scale;

Based on contents of this variable, you can pick the right size of the image to download and render. For external images, we recommend using AlamofireImage that will handle this download/render operation for you.

In Android (Java)

You may use the 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;