Banners.js

Learn how to integrate Topsort with Banners.js

Topsort’s banners.js public library allows marketplaces to display banner ads through a low-code integration. By using a simple HTML tag, the marketplace can connect to Topsort’s ad server and render banners from active campaigns without complex integrations.

Installation

banners.js runs the auction and displays the banner. Load analytics.js with it, so that renders, impressions and clicks on the banner are reported. Install both with npm:

npm install @topsort/banners @topsort/analytics.js

Then import @topsort/banners after setting up analytics.js as described on its page, with window.TS set before either library loads.

Or load them with <script> tags, setting window.TS first:

<script>
  // Global configuration for Topsort
  window.TS = {
    token: "TSE_XXXXXXXXXXXX", // Replace with your Topsort API key
  };
</script>
<script src="https://unpkg.com/@topsort/analytics.js@latest/dist/ts.iife.js"></script>
<script type="module" src="https://unpkg.com/@topsort/banners@latest/dist/banners.mjs"></script>

Usage

This example shows a minimal setup required to do it. The integration works with standard HTML and Javascript, making it compatible with most frontend stacks.

To test it, you just need to add your Marketplace API Key and the banner slot id, configured in the campaign.

<script>
  // Set API key for auctions and events
  window.TS = {
    token: "TSE_XXXXXXXXXXXX",
  };
  // Custom behavior can be configured for each site.
  window.TS_BANNERS = {
    // handle the destination link
    getLink(banner) {
      return `https://example.com/${banner.id}`;
    },
    // handle loading/fetching state
    getLoadingElement() {
      const el = document.createElement("div");
      el.innerText = "Loading...";
      return el;
    },
    // handle errors
    getErrorElement() {
      const el = document.createElement("div");
      el.innerText = "Error loading banner";
      return el;
    },
  };
</script>
<script src="https://unpkg.com/@topsort/analytics.js@latest/dist/ts.iife.js"></script>
<script type="module" src="https://unpkg.com/@topsort/banners@latest/dist/banners.mjs"></script>
<body>
  <topsort-banner width="600" height="400" id="<your slot id>"></topsort-banner>
</body>

Banner Attributes

These are the attributes available for the <topsort-banner> component. They serve as input to the auction request, to fetch the right winners for that context.

Name	Type	Description
width	number	Banner width
height	number	Banner height
id	string	The slot ID for this banner, configured at the campaign
category-id (optional)	string	The category ID of the current page
category-ids (optional)	string	Comma-separated category IDs; the item must match all of them
category-disjunctions (optional)	string	Comma-separated category IDs; the item must match any of them
search-query (optional)	string	The search query of the current page
location (optional)	string	The location for geotargeting
new-tab (optional)	boolean	Opens the banner’s link in a new tab. Defaults to false

Set only one of category-id, category-ids and category-disjunctions. If more than one is set, only the first in that order is used.

Banner Behaviors

These functions on window.TS_BANNERS customize how banners are displayed. All of them are optional.

Name	Returns	Description
getLink(banner)	string	Destination URL of the banner
getLoadingElement()	HTMLElement	A custom element to show while the banner is loading
getErrorElement(error)	HTMLElement	A custom element to show when an error occurs
getNoWinnersElement()	HTMLElement	A custom element to show when the auction returns no banner
getBannerElement(banner)	HTMLElement	A custom element to show instead of the default banner

Banner Interface

The banner interface is the structure of a banner object. Each banner contains metadata about the campaign, and the resolvedBidId, the parameter needed for tracking user interactions (renders, impressions and clicks).

Name	Type	Description
type	”product” | “vendor” | “brand” | “url”	The type of the winning entity, represented by the banner, configured at the campaign.
id	string	The ID of the winning entity. If the entity is of type URL, this is the URL.
resolvedBidId	string	The corresponding bid ID of the winning entity, needed for tracking renders, impressions and clicks.
asset	[{ url: string }]	An array of urls linking to the assets of the banner.
isFallback	boolean (optional)	true for a fallback banner. Fallback banners are not tracked.