Integrating Topsort with Segment

If you use Twilio Segment to track events or actions in your site then you can integrate Topsort events directly on your Segment account by adding the Topsort Destination.

This assumes you have already set up your Segment account and have a working Source to track events in your site. You can learn how to setup a Segment Source for Javascript frontend with this Analytics.js Quickstart Guide. If you want to know more about Segment’s capabilities for tracking and reporting events, please visit the Sources Overview page in Segment’s site.

Setting up an events integration is one of the 3 steps to integrate with Topsort (see Integration Overview for more details). It allows marketplaces to have a full metrics report available through Topsort’s Reporting API or directly in the Topsort Manager Platform dashboards. It also provides the necessary information for the Topsort team to display relevant ads, optimize budget consumption, attribute purchases and accomplish sellers’ conversion goals.

You can follow the steps on the Segment docs or the ones right below to set up the Topsort destination in your Segment account.

Getting started

Intro to Topsort Events

You will need to track 3 main events in your site to integrate with Topsort: Impressions, Clicks and Purchases. Here are the definitions of what these events mean to Topsort:

• Impression: Every time a user sees a promoted product in a listing page (PLP) or section.
• Click: If the user then clicks or adds the promoted product to a cart.
• Purchase: When an order is completed and confirmed to be successful. You can report a purchase whether it has promoted products or not. Topsort takes care of filtering relevant promoted products inside the completed order given the information about promoted clicks.

Topsort’s Segment destination has 3 default presets that map these Segment Track events to the Topsort Events:

Topsort Event	Required	Default mapping	Other mappings
impressions	yes	Product Viewed	Product List Viewed
clicks	yes	Product Clicked	Product Added
purchases	yes	Order Completed	-

The mappings in the Topsort destination are built based on the Segment Ecommerce Spec. For impressions be sure to activate either Product Viewed or Product List Viewed. For clicks you can activate the Product Clicked event and the Product Added event at the same time only if you don’t trigger both events under a single user action, otherwise you’ll be sending duplicated clicks to Topsort. If you use different Track events let us know so we can help you map them to the correct Topsort Events at support@topsort.com.

Set up your Topsort destination

1. From the Segment web app, click Connections > Catalog, then click Destinations.
2. Search for “Topsort” in the Catalog, select the option shown in the screenshot below.
   
3. Click on “Add destination”, and choose which of your sources to connect the destination to.
   
4. In the Topsort Manager Platform, go to Settings > API Integration to find or create your Marketplace API Key for auctions and events.
5. Return to the Topsort destination in the Segment app and enter the value for your Marketplace API Key in the destination Settings tab.
   
6. Enable only the Track events relevant to your site and so that the events do not get duplicated with a single user action.
   
7. Add the resolvedBidId field to the Product Clicked and Product Viewed events. This field is necessary for Topsort to attribute the click or impression to the promoted product. The resolvedBidId is the unique identifier of the promoted product that won the auction. You can find this value in the response of the Auctions API or the proxy response.

8. Please find below an example call to track a product listing page (PLP) click event with the resolvedBidId included:

analytics.track('Product Clicked', {
  productId: '12345',
  resolvedBidId: '67890'
});

Identify

For Segment’s browser and mobile libraries Topsort recommends that you identify your logged-in users using Segment’s Identify method.

Please find an example Identify call below:

analytics.identify('361b1fdfbeaa9d64a13c033eb9f970dc6740f6bc', {
  email: 'john.doe@example.com'
});

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.

If you use a server-side source please provide at least one of the following identifiers: anonymousId or userId.