@topsort/toppie-sdk

Toppie sdk

Toppie sdk is a JS library that allows to integrate Topsort auctions and analytics into your website.

Install in your site

<script src="https://unpkg.com/@topsort/toppie-sdk@0.2.0/dist/main.js"></script>
<script>
  window.toppie.init({ appId: "<your-app-id>" });
</script>

or via npm

npm install @topsort/toppie-sdk

And then in your code

import { toppie } from "@topsort/toppie-sdk";

toppie.init({ appId: "<your-app-id>" });

Banner ads

You can use the ads method to configure and display a banner ad.

<script>
  window.toppie.auctions({
  type: "banners",
  target: {
    selector: ".banner-container",
    width: 2000,
    height: 400,
  },
  auction: {
    slotId: "medium-banner",
  },
});
</script>

| Property | required | Description | |----------|-------------| | type | true | banner | | target.selector | true | Where to display the banner, can be any CSS selector | | target.position | false, default: prepend | append or prepend - location of the banner inside the selector element | | target.width | false | Width of the banner | | target.height | false | Height of the banner | | auction.slotId | true | Slot ID from the Topsort dashboard (learn more about Banners standard sizes) |

Note: A banner ad auction is triggered as soon as to call the ads method. Ads events like impressions will be trigger when the banner is displayed on the page with a threshold of 0.5 or more.

Banners standard sizes

We support the following standard sizes for banners, for example when using the medium-banner slotId, we automatically handle banner size and display the correct banner size.

| Size | width | height | |------|-------------| | "medium-banner" | 300 | 250 | | "wide-skyscraper" | 160 | 600 | | "halfpage" | 300 | 600 | | "leaderboard" | 728 | 90 | | "mobile-1" | 320 | 50 | | "mobile-2" | 300 | 250 |

Custom banner sizes

When your slot has a non-standard size, you can pass the width and height in the ads method.

<script>
  window.toppie.auctions({
    type: "banners", 
    target: {
      selector: ".banner-container",
      width: 1000,
      height: 250,
    },
    auction: {
      slotId: "my-custom-slot", // Slot ID from the Topsort dashboard
    },
  });
</script>

Identify users

The SDK will automatically define an anonymous user id if one is not provided. Alternatively you can identify users with the identify method.

toppie.identify({ userId: "123" });