Twilio Segment

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 Event	Default Segment Mapping	Alternate Mapping
   impressions	Product Viewed	Product List Viewed
   clicks	Product Clicked	Product Added
   purchases	Order 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)

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
   

   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
   

   Prevent double-counting by reviewing your event firing logic.

   2. 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.