Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.topsort.com/llms.txt

Use this file to discover all available pages before exploring further.

Topsort’s analytics.js public library allows marketplaces to easily send Topsort interaction events, such as clicks, impressions and purchases, with a low-code integration. By using a simple HTML tag, the marketplace can connect to Topsort’s ad server and send all tracking events related to an ad.

​
Installation

You can install the library using npm: 
npm install @topsort/analytics.js@2.4.0 --save

​
Configuration

At your application’s entry point, e.g. index.js 
window.TS = {
  token: "<TOPSORT-TOKEN.JS>",
  url: "https://api.topsort.com",
};
// Import the library to initialize it.
import "@topsort/analytics.js";

​
Marking Promoted Elements

To allow Topsort to automatically track clicks, impression and purchases, use the HTML element data-ts-* to mark promoted elements in the page.

​
Organic (non-promoted) elements

<div class="product" data-ts-product="<productId>">...</div>

<div class="product" data-ts-resolved-bid="<resolvedBidId>">...</div>

​
Clickable areas

Use data-ts-clickable to indicate what areas should trigger a click event: 
<div class="product" ...>
  <div data-ts-clickable>
    <img src="https://cdn.marketplace.com/product.png" />
    <span>Product Title</span>
  </div>
  <span>Help</span>
</div>
For banner ads with product attribution: 
<div
  class="product"
  data-ts-product="<productId>"
  data-ts-resolved-bid="inherit"
>
  ...
</div>

​
Purchase tracking

Use data-ts-items JSON array to track purchases: 
<div
  data-ts-action="purchase"
  data-ts-items='[{"product": "product-id-1", "quantity":1, "price": 2399}, {"product": "product-id-2", "quantity": 2, "price": 399}]'
>
  My purchase
</div>

​
End to End Example

Note that banners.js is required for topsort-banner tag, to learn more check Banners.js documentation. 
<script>
  window.TS = {
    token: "<your topsort api key>",
  };
  window.TS_BANNERS = {
    getLink(banner) {
      return `https://example.com/${banner.id}`;
    },
    getLoadingElement() {
      const el = document.createElement("div");
      el.innerText = "Loading...";
      return el;
    },
    getErrorElement() {
      const el = document.createElement("div");
      el.innerText = "Error loading banner";
      return el;
    },
  };
</script>

<body>
  <div class="product" data-ts-product="24-MB03" data-ts-resolved-bid="inherit">
    <topsort-banner
      width="600"
      height="400"
      id="<your slot id>"
    ></topsort-banner>
  </div>

  <div class="product" data-ts-resolved-bid="...">
    <div data-ts-clickable>
      <span>Clickable content</span>
    </div>
    <span>Non clickable content</span>
  </div>

  <div
    data-ts-action="purchase"
    data-ts-items='[{"product": "product-id-1", "quantity":1, "price": 2399}]'
  >
    My purchase
  </div>
</body>