Analytics.js

Integrate and send interaction events with the analytics.js library

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

Load the library with a <script> tag, setting window.TS before the library loads:

<script>
  window.TS = {
    token: "TSE_XXXXXXXXXXXX", // Replace with your Topsort API key
  };
</script>
<script src="https://unpkg.com/@topsort/analytics.js@latest/dist/ts.iife.js"></script>

With npm

npm install @topsort/analytics.js

Imports run before the rest of a module, so set window.TS in a separate file and import that file first:

// topsort-config.js
window.TS = {
  token: "TSE_XXXXXXXXXXXX", // Replace with your Topsort API key
};

// index.js, your application's entry point
import "./topsort-config.js";
import "@topsort/analytics.js";

Do not replace window.TS after the library has loaded. To set the token later, assign window.TS.token instead.

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>

Promoted elements

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

Render tracking

The library reports a render event as soon as a promoted element is inserted into the page, and an impression later, when that element becomes visible. Renders use the same data-ts-resolved-bid attribute, so no extra markup is needed:

<!-- Render: reported when this element is added to the DOM -->
<!-- Impression: reported when it becomes visible to the shopper -->
<div class="product" data-ts-resolved-bid="<resolvedBidId>">...</div>

Renders require an explicit resolvedBidId, so they do not fire for organic elements or for data-ts-resolved-bid="inherit". Do not also report renders, impressions or clicks for these elements with a Topsort SDK, or they are counted twice.

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>

Banner attribution

On the banner’s destination page, mark each product featured in the banner so that its events are attributed to the banner:

<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

This example also uses banners.js for the topsort-banner tag.

<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>
<script src="https://unpkg.com/@topsort/analytics.js@latest/dist/ts.iife.js"></script>
<script type="module" src="https://unpkg.com/@topsort/banners@latest/dist/banners.mjs"></script>

<body>
  <topsort-banner width="600" height="400" id="<your slot id>"></topsort-banner>

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

  <!-- On the banner's destination page: a product featured in the banner -->
  <div class="product" data-ts-product="24-MB03" data-ts-resolved-bid="inherit">...</div>

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