Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.topsort.com/llms.txt

Use this file to discover all available pages before exploring further.

If you’re using Twilio Segment to track events on your site, you can send events to Topsort directly by adding the Topsort Destination in your Segment account. Please refer to Topsort documentation on the Twilio Segments knowledge base. As a prerequisite for this integration, you must have a Segment account and a working Source (website or app).
1

Understand Required Events

Topsort uses three main events, all mapped from Segment’s eCommerce Spec:
Topsort EventDefault Segment MappingAlternate Mapping
impressionsProduct ViewedProduct List Viewed
clicksProduct ClickedProduct Added
purchasesOrder Completed—
  • Avoid sending duplicated clicks. If both Product Clicked and Product Added are fired from the same user action, choose only one.
  • If you’re using custom events, reach out at support@topsort.com to map them properly.
2

Add the Topsort Destination in Segment

  1. In Segment, go to Connections > Catalog > Destinations
  2. Search for Topsort, then click Add Destination
  3. Select the relevant Source (your site or app)
Segment App
3

Configure Destination Settings

  1. In the Topsort Manager Platform, go to Settings > API Integration
  2. Copy or create your Marketplace API Key
  3. Back in Segment, open the Topsort destination’s Settings tab and paste your API Key
Segment Settings
The API Key allows Segment to send events to your Topsort account.
4

Enable Track Events and Add Metadata

  1. Only enable the Track events you’re actively sending from your site
Segment Mappings
Prevent double-counting by reviewing your event firing logic.
  1. Add the resolvedBidId field to:
  • Product Viewed events
  • Product Clicked events
The resolvedBidId uniquely identifies the promoted winner of the auction. You can retrieve it from the Auctions API or Proxy response.Example call:
analytics.track('Product Clicked', {
  productId: '12345',
  resolvedBidId: '67890' // required for Topsort attribution
});
5

Identify Users

Topsort recommends identifying logged users with Segment’s identify method. Example:
analytics.identify('361b1fdfbeaa9d64a13c033eb9f970dc6740f6bc', {
  email: 'john.doe@example.com'
});
Logged-out users are tracked with an anonymousId. If using server-side sources, include at least userId or anonymousId. Once a user is identified, each call to Segment’s Track method automatically records the user ID. Users that are not logged in can be tracked using an anonymousId.