@topsort/banners
Advanced tools
Directly from unpkg.com
<script
async
type="module"
src="https://unpkg.com/@topsort/banners@0.6.0/dist/banners.mjs"
></script>
<script async type="module" src="https://unpkg.com/@topsort/analytics.js"></script>
<script>
// Set API key for auctions and events
window.TS = {
token: "<your topsort api key>",
};
// 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>
You can render multiple banners using the same slot ID and dimensions by setting up
a banner context. This is useful when you want to run an auction with multiple results.
To do that you have to pass the attribute context="true" to the topsort-banner and
use topsort-banner-slot as children elements.
<topsort-banner context="true" width="600" height="400" id="<your slot id>">
<topsort-banner-slot rank="1"></topsort-banner-slot>
<topsort-banner-slot rank="2"></topsort-banner-slot>
<topsort-banner-slot rank="3"></topsort-banner-slot>
</topsort-banner>
| Name | Type | Description |
|---|---|---|
| width | Number | Banner width |
| height | Number | Banner height |
| id | String | The slot ID for this banner |
| category-id* | Optional String | The category ID of the current page |
| category-ids* | Optional String | Comma (,) separated list of category IDs, the item must match all |
| category-disjunctions* | Optional String | Comma (,) separated list of category IDs, the item must match any |
| 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) |
| context | Optional Boolean | Uses the element as a context provider to render multiple banners |
* Only one of [category-id, category-ids, category-disjunctions] must be set.
If multiple are set, only the first will be considered, in that order.
| Name | Type | Description |
|---|---|---|
| rank | Number | The ranking of the slot. Ranks should be sorted the same as the winning bids. The lower the rank, the higher the bid |
| Function Name | Arg type | Return Type | Description |
|---|---|---|---|
getLink | Banner | string | Generates a URL from a banner response |
getLoadingElement | HTMLElement | A custom element to be shown when the banner is loading. | |
getErrorElement | Error | HTMLElement | A custom element to be shown when the banner errors. |
getNoWinnersElement | HTMLElement | A custom element to be shown when the auction returns no banner. | |
getBannerElement | Banner | HTMLElement | A custom clement to be shown when a banner is loaded. |
| Name | Type | Description |
|---|---|---|
type | "product" | "vendor" | "brand" | "url" | The type of the winning entity, represented by the banner. |
slotId | string | The ID of the winning entity. If the entity is of type URL, this is the URL. |
resolvedBidId | string | The corresponding auction ID of the winning entity. |
asset | [{ url: string }] | An array of url linking to the assets of the banner. |
If you want to use your own user identification system instead of the automatic opaque user ID, you can override the getUserId function in the window.TS configuration.
Your custom getUserId function should return the user's ID as a string. You are responsible for generating and persisting the ID (e.g., in a cookie or local storage).
window.TS = {
token: "<your topsort api key>",
getUserId() {
// Return your custom user ID
// This will be used for both auction requests and event reporting
return globalUserId ?? generateAndStoreUserId();
},
};
This configuration needs to be set before analytics.js is loaded or imported.
The banner component emits an event when the state changes. You can listen to this event to write custom logic.
The various states are loading, ready, error, and nowinners.
document.querySelector('#my-slot-id').addEventListener('statechange', (event) => {
console.log(event.detail); // { status: 'ready', banner: { ... } }
});
You can play around with the provided index.html file. To run it, you'll need to install the dependencies and start a local server.
git clone https://github.com/Topsort/banners.js.git
cd banners.js
pnpm install
pnpm run dev
Remember to add window.TS.token and modify the slot-id attribute with your
own values that you can find at Topsort.
FAQs
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
/Security News
Attackers compromised Trivy GitHub Actions by force-updating tags to deliver malware, exposing CI/CD secrets across affected pipelines.
Security News
ENISA’s new package manager advisory outlines the dependency security practices companies will need to demonstrate as the EU’s Cyber Resilience Act begins enforcing software supply chain requirements.
Research
/Security News
We identified over 20 additional malicious extensions, along with over 20 related sleeper extensions, some of which have already been weaponized.