Segment: Enabling the Integration
IMPORTANT NOTE: Gainsight is upgrading Connectors 2.0 with Horizon Experience. This article applies to tenants which are yet to be upgraded to the Horizon Experience of Connectors 2.0. If you are using Connectors 2.0 with Horizon Experience, you can find the documentation here.
Segment is a customer data hub that captures customer usage data from your website and transmits the data to any system that is integrated with Segment. You can integrate Segment with Gainsight to push customer usage data into the Gainsight objects. Segment pushes usage data to Gainsight as and when events are captured by Segment hence there is no configuration required for Schedule in the Segment connector. Example: Usage data can be the pageviews on a product in an ecommerce site or tracking of the customer activities in your website over a period of time. Usage data stored in Gainsight can be analysed and is helpful to design a better product, provide amazing customer service, grow your audience with personalized campaigns, etc.
This article will guide you through how to setup the Segment integration with Gainsight.
Integration of Segment with your Application
You can integrate Segment with your application by installing the Segment web tracking code into your website.
If the Segment web tracking code is already installed on your website, you can skip this step.
Note: You must use your own project's write key.
Tracking Usage Data
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.
- 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 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 Segment.io:
- 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:
- 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.
Configure Segment Integration within Gainsight
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 Tracking Usage Data.
- Integrate Segment with your application by installing web tracking code. For detailed information, refer Integration of Segment with your Application.
- Create or make sure to have custom objects as required for storing Event, People, and Group calls data. These custom objects are used to store usage data retrieved from Segment by API calls Track, Identify, and Group. For more information on how to create custom objects, refer Gainsight Data Management.
To access the Segment.io connector, navigate to Administration > Connectors 2.0 > Connectors.
In the Connectors section, you can see the Segment connector where you can configure its integration with Gainsight.
Create a Segment Connection
Create a connection to integrate Gainsight with Segment. While creating the 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 MDA custom objects. To create a connection:
- Click the Segment.io widget and click the Create Connection icon.
- Enter the following details:
- Name: Enter Connection Name, for example: Mobile Usage.
- Access Key: Click Generate Access Key. A new Access Key is generated. If required, click Reset Access Key to generate a new access key. Copy it to your clipboard.
Note: ‘Date’ and ‘DateTime’ fields in usage data is ingested into the MDA object in UTC timezone.
- Click Create. A Connection is successfully created. You can now create a data job to ingest usage data into MDA objects.
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
While using the Segment connector, you can control the number of events fetched from Segment to Gainsight. There is an option Filter Track Events that helps you to enter specific Segment .track() events. 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.
Navigate to Debugger section in the Segment project. In this page, you can see the events that are filtered. This list helps you to check whether correct events are transmitted to Gainsight.
Create a Segment Data Job
- Click Create Job icon in the connection.
Note: Under one connection, Admins can set up one data job to ingest usage data into the MDA object.
- Three sections, Job Details, Map MetaData, and Review Data appear. In this data job, Segment is integrated with Gainsight to ingest customer usage data of a company’s mobile application.
- In the Job Details section:
- Job Name: Enter a unique Job Name. Consider a job name, Mobile Usage.
- Segment Call Type: Click + icon. 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 Tracking Usage Data.
- Select one or more of the call types.
- In the Notification recipients, enter:
- 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.
- Click Save or Update.
- Under the Required tab, map the required fields between the Segment and MDA object Event for the Event, Time, and Account identifiers as shown below:
- If you want to transform the event records, click Transformation icon in the Event Identifier. Dialog-box for transformation appears.
- In the Transformation dialog-box, you can:
- Assign a default value for the null records
- Change the letter case of the records to lower or upper
- Replace a specific record with another in the Segment event data to be ingested into the MDA objects.
- Click APPLY.
- You can assign default value only in the transformation of the Account Identifier records. Click Transformation icon in the Account Identifier mapping. Transformation dialog-box appears.
- Assign a default value for the null records of Account Identifier and click APPLY.
- Transformation of the Event and Account identifier records is optional.
- You cannot perform transformation on the Time Identifier records.
- Under the Additional tab, click ADD to map any additional fields in Segment to fields in the Event object.
- Under the Required tab, map the required fields between the Segment and the MDA object People for User First Name, Last Name, Email, and Identifier as shown below:
- If required, apply transformation on the First Name, Last Name, Email records of the users. You can assign default value only in the transformation of the User Identifier records. For more information on transformation, refer to Events Mapping.
- Under the Additional tab, click ADD to map any additional fields in Segment to fields in the People object.
- Under the Required tab, map the required fields between Segment and the MDA object Group for Group Name and Identifier as shown below:
- If required, apply transformation on the Group Name records. You can assign default value only in the transformation of the Group Identifier records. For more information on transformation, refer to Events Mapping.
- Under the Additional tab, click ADD to map any additional fields in Segment to fields in the Group object.
- Click Save Mappings.
You can ingest additional usage data on Events, People, and Group into Gainsight at a later point in time. To do this:
- Create new fields in the MDA object that is getting populated with Segment data.
- Map these new fields with Segment fields in the Map MetaData section of the Segment configuration with Gainsight. You can map new fields in all of the three sections: Events, People, and Group.
These new fields are populated with Segment Data for the records that are updated or inserted in the Segment from the date of this field mapping between Segment and MDA object. New fields are not populated with Segment data for all the historic records.
In the Data Jobs section, you can see the list of data jobs performed through Segment. You can edit or delete the existing data jobs from here.
In the Logs tab, you can see the execution and audit logs of the Segment Data Jobs. You can sort the logs with a specific data job.
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 block the transmission of particular events to the Gainsight app. It is recommended to use filtering 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. For more information on how to perform filtering within Segment, refer to the Filter Track Events section.
To block the transmission of particular event’s data from Segment to Gainsight:
- Go to Segment.com website and open your source data.
- Click the Schema tab.
- In the Tracks section, select an event.
- Click the FIlters section.
- 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.
Usage Data Aggregation
You can perform aggregations of the customer usage data with Bionic Rules. To perform the usage data aggregations and to schedule them, refer Tutorial - Aggregate Usage Data with Bionic Rules.