Segment / Amplitude Integration

What is Segment?

Segment allows you to easily manage data and integrations with services across your Growth, Product, and Marketing stack. By tracking events and users via Segment’s API and libraries, you can send your product’s data to all of your analytics/marketing platforms, with minimal instrumentation code. They offer support for most platforms, including iOS, Android, JavaScript, Node.js, PHP, and more.

Amplitude has an excellent partnership with Segment. We have many customers, such as Doordash and Instacart, who successfully send data to our platform via Segment’s various integrations. Once the data is sent to our servers, it is quickly processed and displayed in the Amplitude platform for analysis.

This guide is meant to complement Segment’s integration doc. It provides additional details on the different types of Segment integrations you can use, how they affect your data in Amplitude, and instructions for setting up the integrations.

Getting Started with Segment

1. Sign up for a Segment account: https://segment.com/docs/#getting-started. 
2. Sign up for an Amplitude account: https://amplitude.com/signup.
3. Create a project in Segment: In your Segment workspace, create a project for your application and enable Amplitude as one of your integrations.
4. Create a project in Amplitude: Similarly, create a project for your data on Amplitude. This will generate an API Key for you.
5. Input your Amplitude API Key: Input your new Amplitude API Key into Segment’s Amplitude integration settings panel.
6. Decide on an integration: Decide how you would like to integrate Amplitude and Segment and install the correct Segment library with your chosen integration type for your application. See the setup guide at the end for more detailed steps.
7. Start tracking events: Call Segment's identify and track methods in your application to assign User IDs and track events.
8. Create a chart: build a chart and start exploring!

Pros & Cons of Client-Side Bundled Integration

In addition to Segment's libraries, you can install Amplitude's native SDKs. By doing so, Segment's library will delegate the data collection to our native SDK which will then send the data to our servers. 

Pros:
Adding Amplitude native SDKs adds extra tracking functionality, namely session tracking, and automatic user property tracking.

• Events that are logged within the same user session will be grouped together when viewing that user's stream on Amplitude Dashboard. This also allows for session length calculations on Amplitude's platform.

• The SDKs will also automatically record several user properties such as device type, operating system, and user agent. Here is a list of the user properties tracked automatically by our SDKs.

• Additional Segment Amplitude Integration Setting (in Advanced Settings) -- Track Session Events (disabled by default): If enabled, then the SDKs will automatically send [Amplitude] Start Session and [Amplitude] End Session events to mark the start and end of a user's mobile session.

• With our SDKs installed, you can also directly interact with them. Here are the SDK installation articles that document additional functionality:

• iOS SDK Installation

• Android SDK installation

Cons:
Adding these additional SDKs increases the size of your application (each one is <200kb in space), which you will need to account for if you are already using several libraries in your application (and do note that Android apps can have a max of 65K methods). As mentioned, these additional SDKs are entirely optional and you can still perform pretty much the same analysis in Amplitude by using only Segment's libraries.

• Without session tracking, events will have a session id of -1 so events performed by a user within the same session will not be grouped together in Amplitude’s platform when viewing that user's timeline. In addition, session length calculations will not be available in Amplitude so our User Sessions chart will not display any data. Amplitude's Pathfinder and Pathfinder Users charts will also not be able to display out-of-session events alongside events within a session. You will also not be able to perform session-based Funnel Analysis effectively.
• Without Amplitude's SDKs, you need to map them manually in order to track user properties such as device type and operating system into Amplitude, as described here.

Without Amplitude's SDKs, you need to map them manually in order to track user properties such as device type and operating system into Amplitude, as described here. 

Setting Up Integrations (Sources) into Amplitude

JavaScript (Client-Side)

1. Follow Segment's Analytics.js quickstart guide and paste the snippet onto your website (do not forget to put your Segment write key in the snippet).
2. You are now ready to use track and identify to track users. It's that simple! Analytics.js will also automatically install Amplitude’s native JS SDK onto your website so you can access our JS SDK directly on your website.
   • See our JavaScript SDK Installation documentation for additional functionality provided directly by our JavaScript SDK (you can skip the first three steps of the Installation section).
3. There are some additional settings for the JavaScript integration that you can configure right in the Advanced Settings of your Segment Amplitude integration panel without needing to change any instrumentation code. Here are the settings that pertain to the JavaScript integration:
   • Batch Events (default false): If true, then lets you send events in batches of 30 or every 30 seconds. You can adjust these two thresholds by changing the values of Event Upload Threshold and Event Upload Period Millis.
   • Track All Pages to Amplitude, Track Categorized Pages to Amplitude, and Tracking Named Pages to Amplitude (default false): If true, then calling page will generate 'Viewed ___ Page' events. Note: If more than one of these three options are selected at a time, a single page call will generate multiple events.
   • Track Referrer to Amplitude (default false): If true, Amplitude will capture the user’s referrer, initial referrer, and referring domain as user properties.
   • Track UTM properties (default false): If true, Amplitude will capture UTM properties from URL parameters or the cookie as user properties.

iOS (Client-Side)

NOTE: If you are sending screen calls to Amplitude, make sure to review these destination settings to continue sending screen calls to Amplitude from Segment.

1. Follow Segment's iOS quickstart guide: Install the Analytics pod using Cocoapods, import the SEGAnalytics.h header file, and initialize Segment’s library in your iOS app.

2. At this point, you can start calling track and identify to track users in your app, but you also have the option to install Amplitude's iOS SDK alongside Segment’s library to supplement with additional tracking functionality. The pros and cons of adding Amplitude’s SDK are explained in the previous section. If you choose to, you may follow these extra steps:
   - Install a second pod 'Segment-Amplitude' in Cocoapods:
   pod 'Segment-Amplitude'
   - If you are using Objective-C, then add this second header in the file where you initialized the Segment SDK: 
   #import <Segment-Amplitude/SEGAmplitudeIntegrationFactory.h>
   - If you are using Swift and have use_frameworks! set, then add this second header in the file where you initialized the Segment SDK:
   #import <Segment\_Amplitude/SEGAmplitudeIntegrationFactory.h>

   - Register Amplitude’s SDK with Segment's SDK (this should be done before you initialize Segment's SDK): 
   

   [configuration use:[SEGAmplitudeIntegrationFactory instance]];
[SEGAnalytics setupWithConfiguration:configuration];

3. For examples of how your code should look, see the Segment iOS demo code here. 

Android (Client-Side)

NOTE: If you are sending screen calls to Amplitude, make sure to review these destination settings to continue sending screen calls to Amplitude from Segment.

1. Follow Segment's Android quickstart guide: Install Segment’s library using Gradle and initialize the Analytics client in your Android app. You may also need to update your app’s permissions in the Android manifest file.

2. At this point, you can start calling track and identify to track users in your app, but you also have the option to install Amplitude's Android SDK alongside Segment’s library to supplement with additional tracking functionality. The pros and cons of adding Amplitude’s SDK are explained in the previous section. If you choose to, you may follow these extra steps:
   - Add the following to your build.gradle file:
   compile 'com.segment.analytics.android.integrations:amplitude:+'
   - In the file where you initialize the Segment SDK add:
   import com.segment.analytics.android.integrations.amplitude.AmplitudeIntegration;
   - Register the Amplitude integration with Segment’s SDK. When building the Analytics object, append .use(AmplitudeIntegration.FACTORY) before the .build()
   - So it would look something like this:
   Analytics analytics = new Analytics.Builder(this,"KEY").use
(AmplitudeIntegration.FACTORY).build();
Analytics.setSingletonInstance(analytics);

3. For examples of how your code should look, see the Android demo code here. 

Server-Side and Other Libraries

Follow the Segment guide for your platform.

Mapping Between Segment's API and Amplitude's API

Segment and Amplitude use slightly different nomenclature to describe much of the same functionality. The following table shows the mapping between our two APIs:

For more information see the Segment / Amplitude integration documentation.

Amplitude Engage

The Amplitude Engage product add-on (formerly known as Advanced Cohort Sync) lets you automatically send behavioral audiences to ad networks, marketing automation tools, and personalization engines so you can better tailor campaigns and product experiences.

Details on how to set up this integration can be found here.

FAQ - Segment Integration

1. Why am I not seeing any data in Amplitude?
You have to send data to Amplitude by calling “track”. Data will be visible after you track your first event.

2. Why is the location information (city and/or country) from Segment's data different from the location information in Amplitude's data?
We attempt to determine the user's location from their IP address if available, which may be different from the location information recorded by Segment.

3. Why do I not see any user properties or only [Amplitude] user properties?
In order to send user properties via Segment, you would have to call identify and include your user properties in the traits field. You can read more about their identify call here: https://segment.com/docs/spec/identify/.

4. What is the difference between an event property and user property?
Amplitude allows you to specific event properties and user properties. Here is our help document explaining the difference between the two types of properties.

5.What is the definition of a session?
A session is defined as a period of time that the user has the application open in the foreground. If session tracking is available, then events logged within the same session will have the same Session ID. A new session is started if the application enters the foreground after being in the background or closed for more than 5 minutes.

6. Why do all of my events have a sessionId of -1?
You need to use Segment's client-side bundled integration to have our native SDKs track Session IDs for you.

7. Why are there no session length calculations in Amplitude Dashboard?
See Question 6.

8. What if their SDK doesn’t support feature X? [device-mode]
Since Segment SDK might not have all the APIs our Amplitude SDK provides, however you can still access features by directly calling our SDKs.

Contact Segment support (friends@segment.com) or Amplitude support.