@topsort/toppie-sdk/README.md

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

# Toppie sdk

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

## Install in your site

```html
<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

```bash
npm install @topsort/toppie-sdk
```

And then in your code
```ts
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.

```html
<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](#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.

```html
<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.

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