ad-platform

Analytics.js

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 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/analytics.js@latest/dist/ts.js"
></script>
<script>
  // Global configuration for Topsort
  window.TS = {
    token: "TSE_XXXXXXXXXXXX" // Replace with your Topsort API key
  };
</script>

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. To send events (impressions and clicks) related with an organic (non promoted) element, this marking can be used:

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

To send events (impressions and clicks) related with a promoted element, this marking can be used:

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

Additionally, in case not all the container is clickable (i.e., does not produce an action or does not take you to the product page) or parts of it lead you to a non-related product page, make sure to use the data-ts-clickable attribute to indicate what areas of should trigger a click event. Only elements inside this attribute generate a click.

<div class="product" ...>
  <div data-ts-clickable>
    <img src="https://cdn.marketplace.com/product.png" />
    <span>Product Title</span>
  </div>
  <span>Help</span>
</div>

If you are running a banner ad and need more control over the product purchases that can be attributed to that banner, you can implement a specific markup within the destination page of the banner. This additional markup will allow you to track the attribution process more effectively, ensuring that the right products are associated with the corresponding banner clicks.

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

Finally, the data-ts-items JSON array is the only thing needed to track purchases attributable to the ad. By using it when the purchase is done, Topsort is aware of it and can attribute to the interaction events (clicks and purchases). Here’s an example on how to send these events using the analytics.js library:

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

End to End Example

This is an HTML file with all the elements from banners.js and analytics.js, including fetching and rendering a banner, tracking impressions, clicks and purchases and sending an additional attribution for a related product:

<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@latest/dist/ts.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>
  <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-purchase-1", "quantity":1, "price": 2399}, {"product": "product-id-purchase-2", "quantity": 2, "price": 399}]'
  >
    My purchase
  </div>

</body>