https://github.com/topsort/analytics.js
Topsort's JS analytics event library
https://github.com/topsort/analytics.js
ads analytics sponsored-listings topsort
Last synced: 7 days ago
JSON representation
Topsort's JS analytics event library
- Host: GitHub
- URL: https://github.com/topsort/analytics.js
- Owner: Topsort
- License: mit
- Created: 2022-01-05T15:05:31.000Z (over 3 years ago)
- Default Branch: main
- Last Pushed: 2025-06-18T14:52:31.000Z (27 days ago)
- Last Synced: 2025-07-06T22:52:17.811Z (9 days ago)
- Topics: ads, analytics, sponsored-listings, topsort
- Language: TypeScript
- Homepage:
- Size: 1.18 MB
- Stars: 2
- Watchers: 14
- Forks: 0
- Open Issues: 8
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# Topsort Analytics.js Tutorial
This tutorial will guide you through the process of integrating Topsort's Analytics.js library into your website to track events like impressions, clicks, and purchases.
## 1. Introduction
Topsort's `analytics.js` is a JavaScript library that allows you to automatically report user interaction events with products on your website to Topsort's Analytics service. This helps you understand how users are interacting with sponsored and organic listings.
## 2. Installation
You can install the library using npm:
```bash
npm install @topsort/analytics.js --save
```
## 3. Usage
### Option 1: With a Bundler (e.g., Webpack, Vite)
If you're building a JavaScript application with a bundler, you can import the library directly into your project.
In your application's entry point (e.g., `index.js`, `main.ts`), you need to configure Topsort Analytics *before* you import the library. The library's code runs on import and will look for a global `window.TS` object.
```javascript
// Configure Topsort Analytics
window.TS = {
token: "", // Generate a token for each environment in the Topsort Auction Manager
url: "https://api.topsort.com",
};
// Import the library to initialize it.
// This will start the event listeners.
import "@topsort/analytics.js";
```
The library will automatically start listening for DOM changes and user interactions once it's imported.
### Option 2: With a Local Script File
If you are not using a bundler, you can include the library by serving the file yourself.
First, you'll need to locate the `ts.js` file in your `node_modules` directory at `@topsort/analytics.js/dist/ts.js`. Copy this file to a public directory in your project that is served to the client (e.g., `public/` or `assets/`).
Then, include it in your HTML file with a `` tag. Make sure you configure `window.TS` *before* the script is loaded.
```html
<script>
// Configure Topsort Analytics
window.TS = {
token: "<YOUR-TOPSORT.JS-TOKEN>", // Generate a token for each environment in the Topsort Auction Manager
url: "https://api.topsort.com",
};
```
## 4. Configuration
The configuration is done via the global `window.TS` object, which must be set before the library is loaded.
* `token`: **(Required)** This is your unique Topsort.js token. You can generate a token for each of your environments (e.g., development, production) in the Topsort Auction Manager.
* `url`: **(Optional)** The URL of the Topsort API. Defaults to `https://api.topsort.com`.
## 5. Tracking Impressions
The library automatically detects and reports impressions of products when they become visible on the screen. To enable this, you need to add the `data-ts-resolved-bid` attribute. The value should be the `resolvedBidId` you received from the Topsort API when you ran an auction.
```html
```
## 6. Tracking Clicks
The library can also track when a user clicks on a product. By default, it will consider a click on any part of the product element as a conversion.
If you want more granular control over what constitutes a clickable area, you can use the `data-ts-clickable` attribute. This is useful when only a part of the product container should trigger a click event (e.g., the image and title, but not a "help" icon).
```html
Product Title
Help
```
## 7. Tracking Purchases
To track purchases, you need to add the `data-ts-action="purchase"` attribute to an element that the user interacts with to complete a purchase (e.g., a "Buy Now" or "Complete Purchase" button).
You also need to provide the details of the purchased items using the `data-ts-items` attribute. This attribute should contain a JSON string representing an array of purchased items. Each item object can have the following properties:
* `product_id`: The ID of the product.
* `quantity`: The quantity of the product purchased.
* `price`: The price of the product.
* `vendorId`: (Optional) The ID of the vendor.
```html
Complete Purchase
```
**Note:** The attribute value must be a valid JSON string. Ensure that you properly escape any quotes within the string.
## 8. Advanced Usage
### Banner Clicks
If you are using banners to promote products, you can track clicks on those banners and attribute them to the products on the banner's destination page.
When a user clicks a banner, they are taken to a destination page. On that page, for each product that was featured in the banner, add the `data-ts-resolved-bid="inherit"` attribute. This tells the library that the impression and potential click are a result of the banner interaction.
```html
```
### Overriding User ID
By default, the library manages a user ID to track user sessions. If you want to use your own user identification system, you can override the `getUserId` function in the `window.TS` configuration.
Your custom `getUserId` function should return the user's ID as a string. You are responsible for generating and persisting the ID (e.g., in a cookie or local storage).
```javascript
window.TS = {
token: "",
getUserId() {
// globalUserId is the user id you would like to pass to the analytics
// generateAndStoreUserId is a function that generates a new user id and stores it in a cookie/local storage
return globalUserId ?? generateAndStoreUserId();
},
};
```
This configuration needs to be set *before* the library is loaded or imported.
## 9. Tracking Organic Products
The library can track both impressions and clicks for organic products. This is optional but recommended for a more complete analytics picture of how users interact with all items on your site.
### Organic Product Impressions
To track impressions for an organic product, add the `data-ts-product` attribute with the product's unique ID.
### Organic Product Clicks
Clicks on organic products are tracked automatically when the product element has the `data-ts-product` attribute. If you need to specify which parts of the product element are clickable, you can use the `data-ts-clickable` attribute, just as you would for promoted products.
## 10. Troubleshooting
### "Uncaught Error: Mismatched anonymous define() module"
This error can occur if you are using an AMD loader like RequireJS. This library is not AMD-compatible. You should use the ESM version of the library (`ts.mjs`), which can be imported as a module in modern JavaScript environments, as shown in the "Usage with a Bundler" section.