Table of Contents
- Introduction: What is Segment?
- Getting Started
- Pros & Cons of Client-Side Bundled Integration
- Setting Up Integrations
- Mapping Between Segment's API and Amplitude's API
- Having Integration Issues?
What is Segment?
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.
- Sign up for a Segment account: https://segment.com/docs/#getting-started.
- Sign up for an Amplitude account: https://amplitude.com/signup.
- Create a project in Segment: In your Segment workspace, create a project for your application and enable Amplitude as one of your integrations.
- Create a project in Amplitude: Similarly, create a project for your data on Amplitude. This will generate an API Key for you.
- Input your Amplitude API Key: Input your new Amplitude API Key into Segment’s Amplitude integration settings panel.
- 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.
- Start tracking events: Call Segment's
trackmethods in your application to assign User IDs and track events.
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.
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:
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.
- Note: 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.
- 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
- 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).
- You are now ready to use
identifyto 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.
- 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
pagewill generate 'Viewed ___ Page' events. Note: If more than one of these three options are selected at a time, a single
pagecall 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.
- 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.
- At this point, you can start calling
identifyto 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:
- If you are using Objective-C, then add this second header in the file where you initialized the Segment SDK:
- If you are using Swift and have
use_frameworks!set, then add this second header in the file where you initialized the Segment SDK:
- 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];
- 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.
- At this point, you can start calling
identifyto 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:
- In the file where you initialize the Segment SDK add:
- Register the Amplitude integration with Segment’s SDK. When building the Analytics object, append
- So it would look something like this:
Analytics analytics = new Analytics.Builder(this,"KEY").use(AmplitudeIntegration.FACTORY).build();
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:
|Segment's API||Amplitude's API||Description|
|track (with properties)||logEvent (with properties)||This will log an event with the specified event properties.|
|track with property "revenue"||logRevenueV2||This will log a revenue event to record a revenue amount.|
|identify with traits||setUserId, setUserProperties||This will assign a userId and set any traits as user properties.|
|screen / page with name||logEvent "Viewed" + name||This will log an event "Viewed [page]" where [page] is the name provided.|
|alias||n/a||UserId aliasing is currently unsupported by Amplitude.|
|group||setGroup (with GroupName)||This will allow you to designate user groups.|
For more information see the Segment / Amplitude integration documentation: https://segment.com/docs/integrations/amplitude/.
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.io, 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.
Having Integration Issues?
Contact Segment support (email@example.com) or Amplitude support.