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