For customers already using Segment to collect their event data, we provide a full integration with their data collection service. To learn more about Segment, please visit their website.
Segment events contain information about interactions users have with your product. These interactions can be tracked and logged to Freshsuccess. Each event contains information about the specific interaction. This includes: the time at which the interaction occurred, the module and feature associated with the action, and the account and user ID that performed the action.
In addition to tracking user actions, the integration with Segment can also be used to add information about new users and/or accounts, and update existing users and/or accounts. This document outlines the Segment events and the properties of those events that Freshsuccess requires to perform these tasks.
Modules and features specify a hierarchy by which to categorize events. Modules may include multiple features; while features are mapped to individual clicks or events within a module. E.g., a dashboard is an example of a module, while the specific action of adding a widget to that dashboard is associated with a feature.
Since Segment does not track the time a user spends within the product, Freshsuccess attempts to estimate the time spent within a module and time spent within a session. When we do not see a session ID (Segment anonymousId) for a period of 30 minutes, we 'timeout' the session and compute the time spent within that session. We perform similar calculations to determine the amount of time spent within a module.
The Freshsuccess JS event collector library tracks user idle time and provides much more accurate information regarding the time spent within sessions and modules.
This document outlines the preferred method for integrating Segment with Freshsuccess. We recognize that there are many ways to provide similar information, thus we built Freshsuccess's event collection layer to be flexible enough to support many different mappings. So please contact firstname.lastname@example.org if your mappings are different to those outlined below.
To setup the Freshsuccess Segment integration, a few steps must first be followed. As soon as the integration is enabled within Segment, Freshsuccess will start receiving your data.
The following table outlines the base properties that should be included with each Segment event.
|type||string||yes||Segment event type, one of: 'track', 'identify', 'group'|
|anonymousId||string||yes||unique session id|
|originalTimestamp||string (ISO-8601)||yes||time at which event occured; ISO-8601 string format|
|userId||string||yes||unique id for the user using your product|
|groupId||string||recommended||unique id for the account to which the user belongs; it is highly recommended that the groupId accompany every event. If it does not, then the userId must be globally unique across all accounts, as it will be used to determine the correct groupId|
Freshsuccess uses the Segement Track event to provide the
|event||string||yes||name of feature within Freshsuccess|
|properties.module||string||recommended||name of module within Freshsuccess|
Freshsuccess uses the Segement Identify event to provide additional information about the user and is used to add new product users or update existing product users in the Freshsuccess system. The user details are typically provided within the
|traits.first_name||string||recommended||first name of user|
|traits.last_name||string||recommended||last name of user|
|traits.email||string||recommended||email address of user|
|traits.phone||string||no||primary phone number|
|traits.mobile_phone||string||no||mobile phone number|
|traits.mailing_street||string||no||business street address|
|traits.mailing_city||string||no||business city address|
|traits.mailing_state||string||no||business state address|
|traits.mailing_postal||string||no||business postal/zip code|
Freshsuccess uses the Segement group event to provide additional information about the account and can be used to add new accounts or update existing accounts in the Freshsuccess system. The account details are typically provided within the
|groupId||string||yes||unique id of account|
|traits.name||string||yes for insert||name of company|
|traits.createdAt||string (ISO-8601)||yes for insert||join date; date at which company signed up for your product in ISO-8601 format|
|traits.email||string||recommended||primary contact email|
|traits.description||string||no||short company description (512 chars)|
|traits.phone||string||no||primary phone number|
|traits.website||string||no||website of company|
|traits.industry||string||no||type of business/industry|
|traits.employees||number||no||number of employees|
|traits.tier||string||no||tier to which company belongs (tier name must be set in Freshsuccess account settings)|
|traits.lifecycle_stage||string||no||current stage of company in its lifecycle (stage name must be set in Freshsuccess account settings)|
|traits.billing_street||string||no||business street address|
|traits.biling_city||string||no||business city address|
|traits.billing_state||string||no||business state address|
|traits.billing_postal||string||no||business postal/zip code|
|traits.is_churned||boolean||no||indicates that the account has churned if true|
Freshsuccess can also map arbitrary fields from either the group or the identify call to custom account-level dimensions. Dimensions of the type: string, number, or date are supported. No event-level (other than feature/product/module) or user-level dimensions (other than those specified in the identify call above) are supported.