Gainsight NXT - Articles Impacted due to July, 2023 Release
IMPORTANT UPDATE: Our documentation is being updated to match the new July 2023 release (v6.37) navigation changes. Technical Communication team is working diligently to align everything as soon as possible. Thanks for your support.
For more information about the latest UI changes, click here.
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.
This article will guide you through how to setup the Segment integration with Gainsight.
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 ingest 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.
Note: Currently, Segment connector is not available for Europe region.
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 following 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 the Tracking Usage Data section in this article.
Integrate Segment with your application by installing web tracking code. For detailed information, refer to the Integration of Segment with your Application section in this article.
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.
- Click the CONNECTORS tab.
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 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. To create a connection:
- Click the Segment.io widget
- Click the Create Connection icon. Create a Connection window is displayed.
- 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 Gainsight object in UTC timezone.
- Click CREATE. A Connection is successfully created. You can now create a data job to ingest usage data into Gainsight 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 Gainsight 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 the + 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 the Tracking Usage Data section in this article.
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 Gainsight 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 Gainsight 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 Gainsight 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 Gainsight 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 Gainsight 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 Gainsight 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:
- Navigate 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 on the customer usage data with Rules. To perform the usage data aggregations and to schedule them, refer Aggregate Usage Data with Rules Engine.