Skip to main content
Gainsight Inc.

Segment Connector

  1. Last updated
  2. Save as PDF 
Gainsight NXT

 

IMPORTANT: Gainsight is upgrading Connectors 2.0 with Horizon Experience. This article applies to tenants which have been upgraded to the Horizon Experience for Connectors 2.0. If you are using Connectors 2.0 with the previous version, you can find the documentation here.

This article explains how to integrate Segment with Gainsight to access all Segment event data in Gainsight.

Note: This document provides general guidance on creating a Connection. The use case of each job is different and needs a unique configuration. For more information on how to create any Job, refer to the Configuration of Connectors in the Additional Resources section at the end of this article.

Overview

Segment is a customer data hub that captures customer usage data from your website and transmits the data to Gainsight that is integrated with Segment.

Integrate Segment with Gainsight to ingest customer usage data into the Gainsight objects. Segment integration pushes usage data to Gainsight as and when events are captured by Segment, hence configuration is not required for Schedule of the data jobs.

For example, usage data includes the pageviews on a product in an ecommerce site or tracking of the customer activities in your website over a period of time.

Note: Currently, the Segment connector is not available for the Europe region and the US 2 region.

Benefits of Gainsight integration with Segment: Analyze the Usage data stored in Gainsight to design a better product, provide amazing customer service, grow your audience with personalized campaigns, etc.

Configure Segment Integration within Gainsight

Recommendations

Gainsight supports three call types: Event, People, and Group which are equivalent to Segment API calls Track, Identify, and Group. For more information on these Segment API calls, refer to the Track Usage Data section in this article.

Prerequisites

  1. Integrate Segment with your application by installing web tracking code. For more information, refer to the Integration of Segment with your Application section in this article.
  2. Create or ensure that you have custom objects as required for storing Event, People, and Group calls data. These custom objects are used to store usage data fetched from Segment through the API calls Track, Identify, and Group. For more information on how to create custom objects, refer to the Gainsight Data Management in the Additional Resources section at the end of this article.

Integration of Segment with your Application

Segment is integrated with the application by installing the Segment web tracking code into the website.

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

For more information about how to add the Segment Javascript library directly to your website, refer to the Quick Start: Analytics.js article. The following image displays an example of the web tracking code.

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

Web Tracking code.png

Track Usage Data

Track Segment data to design a better product, provide amazing customer service and grow your audience with personalized campaigns. Gainsight supports three call types: Event, People, and Group which are equivalent to Segment API calls Track, Identify, and Group. The following tracking code snippet contains three properties that are recommended to use for the Segment integrations.

Tracking code.png

Following are the properties of the webpage tracked using Segment:

  • To track page loads with Segment, you should add a track API call that is called when the page is loaded.
  • Gainsight supports three types of Segment API calls while tracking customer usage data. They are identified as Segment fields while mapping to the target Gainsight fields. Purpose of the Segment API calls is explained below:
    • Identify: Links users to their actions on the UI and records 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  users update their info (example: change or adds a new address)
      • (optional) On loading pages that are accessible by a logged in user
    • Track: The Track API call helps you record any actions that the users perform, along with any properties that describe the action.
    • Group: The Group API call helps 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.

Limitation

Gainsight does not support the following three types of calls from Segment:

  • Page
  • Alias
  • Screen

Details related to the page should be passed as properties with the event. For example, pass the following three properties along with the pageLoad event:

  1. 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.
  2. 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.
  3. 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 web page should look similar to the following example.

Segment Code.png

Create a Segment Connection

You can create a connection to integrate Gainsight with Segment. While creating a connection, an access key will be generated. This is used to integrate Gainsight in the Segment website. Once a connection is created, a data job is configured to ingest usage data into the Gainsight custom objects.

Note: Create more than one Segment Connection in the Administration > Connectors 2.0 > Connections page.

To create a connection with Segment:

  1. Navigate to Administration > Connectors 2.0.
  2. Click Create Connection. Create Connection dialog appears.
  3. Select Segment in the Connector dropdown list.
  4. Enter the following details:
    1. Name: Enter a unique name of the connection.
    2. Time Zone: Select the Time Zone from the dropdown list. Always select a timezone in which your project is configured in the Segment website.
    3. Access Key: Click Generate Access Key for the first time. A new Access Key is generated. If required, click Reset Access Key to generate a new access key. Copy the access key to your clipboard.
  5. Click Save. A Connection is successfully created. Create a data job to ingest usage data into the Gainsight objects.

    Create Connection.png

Integration of Gainsight with Segment

Segment Admins should set up a few configurations in their Segment accounts to  integrate Gainsight with Segment For more information on these configurations, refer to the Gainsight Destination Segment documentation.

Filter Track Events in Segment

Segment Admins can control the number of events pushed from Segment to Gainsight. There is an option to filter Track Events that controls entering specific Segment .track() events to Gainsight. If you do not filter any events, Segment sends all .track() events which may be abundant and not useful in Gainsight. It is recommended to filter the Segment events to control the number of events that are transmitted to Gainsight. For more information on how to filter Track Events, refer to the Segment documentation.

Transmit Selective events to Gainsight from Segment

While integrating  Gainsight with Segment, if you know that a particular events data in Segment will not be used in Gainsight, you have the option to block the transmission of particular events to the Gainsight app.  It is recommended to filter track events in Segment to control the number of events that are sent to Gainsight. Sending an abundance of unnecessary events can slow down the Segment infrastructure for all users.

To block the transmission of a particular event’s data from Segment to Gainsight, refer to the How do I filter specific events from being sent to specific Destinations? Segment documentation.

Usage Data Aggregation

Perform aggregations on the customer usage data with Rules. For more information, refer to the Aggregate Usage Data with Rules Engine in the Additional Resources section at the end of this article.

Debug Events

Segment Admins can see the filtered events in the Debugger section of the Segment project. This list helps to check whether correct events are transmitted to Gainsight. For more information, refer to the Using the Source Debugger Segment document.

Create a Segment Data Job in Gainsight

This section explains how to create a Segment data job in Gainsight. For example, create a Segment data job to sync customer usage data of a company’s mobile application.

Note: Create one data job for each Segment connection in the Administration > Connectors 2.0 > Connections page.

To create a Segment data job:

  1. Navigate to the Jobs page.
  2. Click the Create Job. The Create Job dialog appears.
  3. Enter the Job Name in the Name of the Job textbox.
  4. Click Next. The Job Preparation page appears.
  5. Select Segment connection in the Data Source. Preparation tab is displayed.

    The following two sections are displayed:
    • Job Details
    • Map Metadata

Create Job.png

Job Details

  1. In the Job Details section:
    1. Job Name: Enter a unique name of the Job. For example, Mobile Usage.
    2. Segment Call Type: Click the + icon to add call types. Gainsight supports three call types: Event, People, and Group to track customer usage data. These call types are equivalent to Segment call types: Track, Identify, and Group. For more information on the Segment call types, refer to the Tracking Usage Data section in this article.

      Note: You can select one or more of the call types based on the requirement.
    3. In the Send Email Notifications, enter the email address of recipients for the following cases:
      • Success recipients: If metadata import is successful, a success notification email is sent to the email address entered here.
      • Failure recipients: If metadata import is failed, a failure notification email is sent to the email address entered here.
    4. Click Save.

      Create Job_2.png

Map MetaData

Events Mapping

In the Events Mapping section, perform the following actions:

  1. Select a Gainsight custom object to load events data from Segment. For example, SegmentObject as shown below.
  2. In the Required tab, map the required fields between the Segment and Event (Gainsight object) for the Event, Time, and Account identifiers as shown below:

    Map Meta Data.png

  3. (Optional) Transformation:

    1. Click the Transformation icon in the Event Identifier to transform the event records. Dialog-box for transformation appears.

      Note: You cannot perform transformation on the Time Identifier records.
       
    2. In the Transformation pop-up window:
      • Default value: Assign a default value for the null records.
      • Change case: Change the letter case of the records to lower or upper.
      • Replace: Enter the name of  specific record with another in the Segment event data to be ingested into the Gainsight objects.
      • With: Enter the value for the source record to be replaced with this value.
    3. Click APPLY.
    4. You can assign default value only in the transformation of the Account Identifier records. Click the Transformation icon in the Account Identifier mapping. Transformation dialog-box appears.
    5. Assign a default value for the null records of Account Identifier and click APPLY.

      Transformation Event.png
       
  4. In the Additional tab, click ADD to map any additional fields in Segment to fields in the Event object.

    Event Mapping.png

People Mapping

In the People Mapping section, perform the following actions:

  1. Select a Gainsight custom object to load events data from Segment. For example, People as shown below.
  2. In the Required tab, map the required fields between the Segment and the Gainsight object People for User First Name, Last Name, Email, and Identifier as shown below:

    People Mapping.png
     
  3. If required, apply transformation on the First Name, Last Name, Email records of the users. Assign default value only in the transformation of the User Identifier records. For more information on transformation, refer to Events Mapping under Map MetaData section.
  4. In the Additional tab, click ADD to map any additional fields in Segment to fields in the People object.

Group Mapping

In the Group Mapping section, perform the following actions:

  1. Select a Gainsight custom object to load events data from Segment. For example, Group as shown below.
  2. In the Required tab, map the required fields between Segment and the Gainsight object Group for Group Name and Identifier as shown below:

    Group_Mapping.png
     
  3. If required, apply transformation on the Group Name records. Assign default value only in the transformation of the Group Identifier records. For more information on transformation, refer to Events Mapping under Map MetaData section.
  4. In the Additional tab, click ADD to map any additional fields in Segment to fields in the Group object.
  5. Click Save Mappings.

Ingest additional usage data on Events, People, and Group into Gainsight at a later point in time. To configure this:

  1. Create new fields in the Gainsight object to populate the respective Segment data.
  2. Map these new fields with source Segment fields in the Map MetaData section of the Segment data job. Map new fields in all of the three sections: Events, People, and Group.

These new fields are populated with latest Segment Data from the date of setting up these configurations. New fields are not populated with Segment data for all the historic records.

Activities

View the Execution and Update Activities of all the data jobs in the Activity page. Download the logs of the job execution from this page to help troubleshoot the configuration issues. For more information, refer to the Activity Page in the Additional Resources section at the end of this article.

  1. Back to top
  • Was this article helpful?

Recommended articles

  1. Article type
    Topic
  2. Tags
    This page has no tags.