Skip to main content
Gainsight Inc.

Segment: Enabling the Integration

If you are interested in using the integration using the connector,  contact for approval.

This article will guide you through how to setup the Segment integration.

To integrate segment with Gainsight, follow these steps:  

  1. Install web tracking code
  2. Identifying Accounts
  3. Tracking page loads
  4. Activate Gainsight MDA Backend
  5. Configure Segment Integration within Gainsight
  6. Map Segment Events and Properties to MDA Equivalents
  7. Link Usage Data ID Field to Salesforce
  8. Add Required and Optional Fields
  9. Gainsight Measure selection
  10. Schedule Aggregations
  11. (optional) Selectively transmit events to Gainsight app

Install Web Tracking Code

If the Segment web tracking code is already installed on your website, you can skip this step.

If Segment is not installed on your website, follow the instructions in this link to add the Segment Javascript library directly to your site. The following image displays an example of the web tracking code.

Note: You must use your own project's write key.

1. Install Web Tracking Code

Identifying Accounts

Metrics for a user on your site can only be viewed in Gainsight if there is a unique Account identifier present for that user in both Segment and Salesforce. Lets call this the Usage Data ID. The Usage Data ID can be a string or number.

Examples of valid Usage Data IDs are:

  • Salesforce Account ID
  • Fully qualified domain name
  • Account identifier used internally at your company

Examples of invalid Usage Data IDs are:

  • Email addresses (may be more than one per account)
  • Customer Name (prone to inconsistencies)
  • Contract Date (neither string nor number)

Once you have decided on a Usage Data ID, you must ensure that it is present in both Segment and Salesforce. The Usage Data ID must be kept updated in both locations.

  • Salesforce - You must store the Usage Data ID on the Salesforce Account object. Gainsight recommends that you add a new field to the Account object to store this value. For assistance with adding SFDC customer fields, contact your Salesforce Administrator.
  • Segment - The Usage Data ID should be stored in Segment using the identify method. This will ensure that all actions for the user that are tracked through Segment will be associated with the Usage Data ID.
    • Add the following line to the web tracking code used on every page:

Where <Usage Data ID> uniquely identifies the account from which the customer is associated. This may require extra code elsewhere in your application to ensure the Usage Data ID is retrieved in time.

Tracking Page Loads

3. Tracking Page Loads

The above code snippet contains three properties that are recommended to use for Segment integrations.

Segment is a powerful event-based data syndication service. In this documentation, how to track page loads are only covered as part of the Gainsight integration.

  1. To track page loads with Segment, you should add a track API call that is called when the page is loaded.
  2. Gainsight supports three types of Segment events while tracking page loads. They are identified as Segment fields while mapping to the MDA equivalents. The Segment fields and their purposes are explained below:
  • Identify: allows you to tie a user to his actions on the UI and record traits about them. It includes a unique User ID and any optional traits like their email, name, etc. An account can be Identified in the following instances:
    • After a user registers
    • After a user logs in
    • When a user updates their info (example: changes or adds a new address)
    • Upon loading any pages that are accessible by a logged in user (optional)
  • Track: The Track API call is how you record any actions your users perform, along with any properties that describe the action.
  • Group: The Group API call is how you associate an individual user with a group like a company, organization, account, project, or team. It also lets you record custom traits about the group, like industry or number of employees. Calling Group is required if you have accounts with multiple users.

Gainsight does not support the following three types of calls from

  • Page
  • Alias
  • Screen
  1. Details related to the page should be passed as properties with the event.
  2. Pass thefollowing three properties along with the pageLoad event:
    • pageTitle- This property tracks the name assigned to the page, ignoring URL structure. Best suited for websites where almost every URL is unique or where the URLs do not follow a folder structure.
    • pagePathLevelOne- This property groups URLs into a folder hierarchy and aggregates metrics for all pages under the top level folder. Best suited for websites with a large number of URLs organized hierarchically.
    • pageURL- This property tracks every page individually. Best suited for websites with a small number of distinct URLs.

If you pull all the Segment code together, your code on the webpage should look similar to the following example.

Activate Gainsight MDA Backend

Gainsight pulls usage data in through the MDA backend. Before you can pull data from Segment, you must activate the MDA. If you have already set this up for other MDA features, you may skip this step.

In order to activate MDA, your Salesforce user must have the Gainsight Administrator permission set.

For details on how to apply this permission set to your user, please view the following documentation: Gainsight Permission Sets

  1. In Gainsight, navigate to  Administration > Connectors page. If you have any trouble while accessing this page, contact Gainsight Support (

  1. Activate the Authorize MDA switch.

  1. Click Authorize. A window appears asking for permissions.

  1. Click Allow. This action authorizes Gainsight MDA to use your Salesforce data.

  1. After clicking on Allow, close the window. A new brower window appears and displays the message Authorization Successful.

Configure Segment Integration within Gainsight

Before the Segment Integration can be configured, you must first activate the Segment Connector by activating the Segment switch. Additionally, you cannot continue the integration setup until you have received data once, which may require waiting a few hours.

  1. In Gainsight, navigate to Administration > Connectors.

5. Configure Segment Integration within Gainsight

  1. Type a project name for the Segment integration.
  2. Select a time zone that you use in Segment.

  1. Click Generate Access Key.

  1. An access key will be generated. Click the eye icon to see the code.

  1. Once the Key is revealed, copy it to your clipboard.
  2. In a separate browser tab or window, go to and view the integrations for your project.
  3. Set the Gainsight integration switch to ON.

  1. Click the Gainsight logo to view segment settings for the Gainsight integration.

  1. Paste the access key from the clipboard in the text box.
  2. Click Save and Close.
  3. Navigate to Gainsight Integration page and click Next button.

Note: If you see an error at the bottom of the page, consider it as a normal event. It may take a few hours for Gainsight to receive data from Segment and load it into the MDA backend.

Map Segment Events and Properties to MDA Equivalents

You should now see four primary fields that you need to identify for the MDA backend. While mapping Segment fields to the MDA equivalents, Gainsight supports three types of Segment fields: Identify, Track, and Group for data integration. Select the fields as shown in the image above and then click Next.

Link Usage Data ID Field to Salesforce

7. Link Usage Data ID Field to Salesforce

  1. In the step 4, you are prompted to select an Account-Identifier and an User-Identifier.
  2. As part of onboarding, User-Identifier is not configured, clear the checkbox at step 5.
  3. For the Account-Identifier, select the field from the drop-down list that contains the Usage Data ID on Account object.
  4. After the page appears completely, click Next.

Add Required and Optional Fields

8. Add Required and Optional Fields

  1. In step 6, under the Add Required Fields section, ensure that Salesforce is selected in the first drop-down list and track distinct_id is selected as shown in the above image.
  2. In step 7, under Add Optional Fields, select the properties shown in the image above, along with the corresponding labels.
  3. Click Next.

Note: You can add up to six optional fields.

Gainsight Measure selection

9. Gainsight Measure selection

Select pageLoad event from the drop-down list, and then click Next.

Schedule Aggregations

10. Schedule Aggregations

  1. In the final step of the configuration, select the Schedule button.
  2. In the Schedule dialog, select daily and Every day as the frequency.
  3. Set Start Date as today and End Date as Dec. 31, 2020.
  4. Set Preferred Start Time to occur shortly before midnight in your time zone.
  5. Click Save and Run.

Selectively transmit events to Gainsight app

While using the Segment connector, if you know that a particular event's data in Segment will not be used in Gainsight, you have the option to not transmit particular events to the Gainsight app.  It is recommended to use Whitelabeling to control the number of events that are sent to Gainsight. Sending an abundance of unnecessary events can slowdown the Segment infrastructure for all users. For more information on how to set up Whitelabeling within Segment, see the Segment Gainsight Integration document.

  1. Go to website and open your source data.
  2. Click Schema tab.
  3. In Tracks section, select an event.
  4. Click FIlters section.
  5. Set the Gainsight filter to ON/OFF as per your requirement. If you set this filter to OFF, the event's statistics will not be transmitted to the Gainsight app. Similarly, if you set it to ON, the event's statistics are sent.
  • Was this article helpful?