Introducing Topsort API V2, your faster and more versatile solution for banner ads! Now you can display ads across multiple pages and devices with different sizes. Curious? Find our API reference here.

Banner ads V2 sync with Topsort API V2 and feature three new variable fields:

Request

Here's a JSON example of a banner ad type auction request for a category page:

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

Response

You'll receive up to 5 auction results, sorted from highest to lowest bid. If no qualifying bids or an error occurs, the array will be empty. A new boolean variable, error, indicates successful auction resolution.

Here's an example JSON response for API V2:

{
  "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
    }
  ]
}

Banner Ad Variables

API V2 requires two variables for banner ads: resolvedbidId and url. The resolvedbidId simplifies event attribution and recording for you and your vendors. Store it as a cookie, session variable, or internal variable, depending on your app type.

The url is a banner asset source URL, served by Topsort's CDN. It's part of the asset array containing the winning vendor's creative URLs.

📘

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.

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.

Render Banners 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 your mobile app code.

On the Campaign API implementation, when you request a banner auction, you will receive as a response a list of winners, each winner will have a reference so that you can trace back the object that must be shown to the user.

This reference is set when you create the campaign, it's called ‘target’. As a target, you can choose between: "product", "brand", "vendor", and "url".

The auction response will provide the target object inserted in the campaign so that you can use this object to get the creative to be rendered.

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 the contents of this variable, you can pick the right size of the image to download and render. For external images, we recommend using AlamofireImage which 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;