Skip to content
Toposort Logo
ad-platform

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.

NameTypeDescription
widthnumberBanner width
heightnumberBanner height
idstringThe slot ID for this banner, configured at the campaign
Category-id (optional)stringContextual category for targeting
Search-query (optional)stringContextual 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.

NameTypeDescription
getLink(banner)stringDestination URL of the banner, configured at the campaign.
getLoadingElementHTMLElementA custom element to be shown when the banner is loading.
getErrorElementHTMLElementA 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).

NameTypeDescription
type”product” | “vendor” | “brand” | “url”The type of the winning entity, represented by the banner, configured at the campaign.
idstringThe ID of the winning entity. If the entity is of type URL, this is the URL.
resolvedBidIdstringThe 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.