Integrating with Segment

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.

Overview

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.

Features and Modules

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.

Limitations

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.

Other mappings

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 support@freshsuccess.com if your mappings are different to those outlined below.

Setup

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.

  1. Using the Freshsuccess web app navigate to the IT Administration Center (under Settings) and retrieve the Event API key and the Event auth key. Contact support@freshsuccess.com if you are unable to login to our product.
  2. Once your Freshsuccess API keys are provided, log into your Segment account.
  3. In Segment, search for the Freshsuccess application.
  4. Turn on the Freshsuccess application and fill in the required Send Key (the Freshsuccess Event API Key) and Auth Key (the Freshsuccess Event Auth Key).
  5. Select the correct datacenter, EU or US based on the location of your Freshsuccess datacenter. If unsure contact support.
  6. Click "SAVE AND CLOSE".
  7. Notify support@freshsuccess.com that the integration has been enabled to verify that data is being received by Freshsuccess.

Base Segment properties

The following table outlines the base properties that should be included with each Segment event.

Object properties
Segment property Type Required Description
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

Track event: Freshsuccess features & modules

type: track | specification

Freshsuccess uses the Segement Track event to provide the feature and module associated with the user's action.

Object properties
Segment property Type Required Description
event string yes name of feature within Freshsuccess
properties.module string recommended name of module within Freshsuccess

Identify event: Freshsuccess user update

type: identify | specification

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 property.

Object properties
Segment property Type Required Description
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.salutation string no Mr/Mrs/Miss, etc.
traits.title string no company title
traits.role string no company role
traits.department string no company department
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
traits.mailing_country string no business country

Group event: Freshsuccess account update

type: group | specification

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 traits property.

Object properties
Segment property Type Required Description
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.billing_country string no business country
traits.is_churned boolean no indicates that the account has churned if true

Custom account dimensions

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.