Banners.js

Topsort’s banner.js public library allows marketplaces 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

You can install the library using npm or yarn, or load the SDK directly in your HTML file by including a <script> tag:

<script
  async
  type="module"
  src="https://unpkg.com/@topsort/banners@latest/dist/banners.mjs"
></script>
<script>
  // Global configuration for Topsort
  window.TS = {
    token: "TSE_XXXXXXXXXXXX", // Replace with your Topsort API key
  };
</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
  async
  type="module"
  src="https://unpkg.com/@topsort/banners@latest/dist/banners.mjs"
></script>
<script
  async
  type="module"
  src="https://unpkg.com/@topsort/analytics.js/dist/ts.js"
></script>
<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>
<body>
  <topsort-banner width="600" height="400" id="<your slot id>"></topsort-banner>
</body>

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	Contextual category for targeting
Search-query (optional)	string	Contextual keyword for targeting

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
getLink(banner)	string	Destination URL of the banner, configured at the campaign.
getLoadingElement	HTMLElement	A custom element to be shown when the banner is loading.
getErrorElement	HTMLElement	A custom element to be shown when an error occurs.

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 (clicks and impressions).

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 user interaction (clicks, impressions) with the ad.
asset	[{ url: string }]	An array of urls linking to the assets of the banner.

Overview

Ad Platform

Ad Server

Toppie

Advanced Integrations

API

Installation

Usage

Banner Attributes

Banner Behaviors

Banner Interface

​Installation

​Usage

​Banner Attributes

​Banner Behaviors

​Banner Interface

Installation

Usage

Banner Attributes

Banner Behaviors

Banner Interface