Amplitude
Step-by-step guide to send your event data from RudderStack to Amplitude
Amplitude is a comprehensive product analytics platform for the web as well as mobile platforms. Over 12,000 companies use Amplitude to get useful marketing insights that drive product strategy and conversion and retention of their customers.
RudderStack supports sending events from the RudderStack SDKs to Amplitude through our data plane and Web connection mode.
Find the open-source transformer code for this destination in our GitHub repo.
Getting started
Before configuring Amplitude as a destination in RudderStack, verify if the source platform is supported by Amplitude by referring to the table below:
Connection Mode
Web
Mobile
Server
Device mode
Supported
Supported
-
Cloud mode
Supported
Supported
Supported
To know more about the difference between cloud mode and device mode in RudderStack, refer to the RudderStack Connection Modes guide.
Once you have confirmed that the source platform supports sending events to Amplitude, follow these steps:
From your RudderStack dashboard, add the source. Then, from the list of destinations, select Amplitude.
Assign a name to the destination and click on Next.
Connection settings
To successfully configure Amplitude as a destination, you will need to configure the following settings:
API Key: You can find the Amplitude API key in the Amplitude dashboard.
API Secret Key required for deletion of users: Enter your API Secret Key required for user deletion.
Residency Server: Based on the Amplitude data center you have configured, select the residency server from the below options:
Standard Server
EU Residency Server
Group settings
Group name trait: The trait that we will use as
groupType
in thegroup
call.Group value trait: The trait that we will use as
groupValue
in thegroup
call.
Track pages
These settings can be used for tracking via web and mobile device mode only.
Track all pages: If this setting is enabled, an event named
Loaded a page
/Loaded a Screen
will be sent to Amplitude.Track Categorized pages: If this setting is enabled and if
category
is present in apage
/screen
call, then an event namedViewed {category} page
/Viewed {category} Screen
will be sent to Amplitude.Track Named pages: If this setting is enabled and the
name
is present in apage
call, then an event namedViewed {name} page
will be sent to Amplitude.
If name
is present in a screen
call, then RudderStack sends the event name as Viewed {name} Screen
to Amplitude. However, if name
is absent, then the event is sent as Loaded a Screen
.
If multiple settings are enabled, then multiple events may be sent for a single page/screen
call. For example, if both Track categorized page and Track named page settings are enabled, one Viewed {name} page / Viewed {name} Screen and one Viewed {category} page / Viewed {category} Screen events will be generated for a single page/screen
call.
Trait settings
This setting is for configuring the traits sent to Amplitude via RudderStack's identify
call.
Traits to increment: If this setting is enabled, the value of the corresponding trait will be incremented at Amplitude, with the value provided against the trait in an
identify
call.Traits to set once: If this setting is enabled, the value of the corresponding trait will be set once at Amplitude with the value provided against the trait in an
identify
call.Traits to Append: If this setting is enabled, the value of the corresponding trait will be appended to the corresponding trait array at Amplitude. If the corresponding trait does not have a value set yet, it will be initialized to an empty list before the new values are appended. If the corresponding trait has an existing value and it is not a list, it will be converted into a list with the new value appended.
This feature is not applicable for the web device mode integration.
Traits to Prepend: If this setting is enabled, the value of the corresponding trait will be prepended to the corresponding trait array at Amplitude. If the corresponding trait does not have a value set yet, it will be initialized to an empty list before the new values are prepended. If the corresponding trait has an existing value and it is not a list, it will be converted into a list with the new value prepended.
This feature is not applicable for the web device mode integration.
Other settings
Track Products once: If this setting is enabled and if the event payload contains an array of products, then the event is tracked with the original event name and all the products as its property. Otherwise, each product is tracked with event as
Product purchased
.Track Revenue per product: If this setting is enabled and if the event payload contains multiple products, each product's revenue is tracked individually.
Version Name: The value of this field is set as the
versionName
of the Amplitude SDK.
This feature is applicable only for the web device mode integration.
Map device brand: Enable this setting for RudderStack to send the device brand information (
context.device.brand
) to Amplitude.
Amplitude computes device_family
as device_family: {device_brand} {device_manufacturer} {device_model}
.
Client-side events filtering
Refer to the Client-side Events Filtering guide for more information on this setting.
Web SDK settings
Batch events: If this setting is enabled, the events are batched together and uploaded by the Amplitude SDK only when the number of queued events is greater than or equal to
eventUploadThreshold
oreventUploadPeriodMillis
(in ms), since the first unsent event is queued.Event upload period millis: If the
batch events
settings is enabled, this is the amount of time that the SDK waits to upload the events.Event upload threshold: If the
batch events
settings is enabled, this is the minimum number of events to batch together by the Amplitude SDK.Use device mode to send events: Enable this flag to send the events through Amplitude web SDK. The other web SDK-supported settings will also work if you enable this option.
Prefer Anonymous ID for Device ID: If this setting is enabled, the Device ID will be set as the
anonymousId
generated by RudderStack SDK or by the value you explicitly set as theanonymousId
via RudderStack'ssetAnonymousId()
method.
For more information on explicitly setting the anonymousId
, refer to the JavaScript SDK documentation.
Set Device ID from the URL parameter: If this setting is enabled, the Amplitude SDK will parse the URL parameter and set the Device ID from
amp_device_id
.Force HTTPS: If this setting is enabled, the events will always be uploaded by the Amplitude SDK to the
HTTPS
endpoint, otherwise it will use the embedding site's protocol.Track GCLID: If this setting is enabled, the Amplitude SDK will capture the
gclid
URL parameters along with the user'sinitial_gclid
parameters.Track Referrer: If this setting is enabled, the Amplitude SDK will capture the
referrer
andreferring_domain
for each session along with the user'sinitial_referrer
andinitial_referring_domain
.Track UTM properties: If this setting is enabled, the Amplitude SDK parses the UTM parameters in the query string or
_utmz
cookie and includes them as user properties in all uploaded events.Save Referrer, URL Params, GCLID once per session: If this setting is enabled, the corresponding tracking of
gclid
, referrer, UTM parameters will be done once per session.
Disable this option if you always want to capture new values through the session.
Unset param referrer on new session: If this setting is disabled, the existing
referrer
andutm_parameter
values will be passed to each new session. If enabled,referrer
andutm_parameter
properties will be set tonull
upon instantiating a new session.
This feature works only if the Track Referrer and Track UTM properties settings are enabled in the dashboard.
Adding device mode integration
iOS Android React Native Follow these steps to add Amplitude to your iOS project:
In your
Podfile
and add theRudder-Amplitude
extensionAfter adding the dependency followed by
pod install
, you can add the imports to yourAppDelegate.m
file as shown:and also add the initialization of your
RSClient
as shown:Add the below logic just after initializing
RudderClient
inAppDelegate.m
if you would like to sendIDFA
of iOS device asdevice id
to AmplitudeMake sure that you enable
use IDFA as device id
underiOS SDK settings
on dashboard.and then add the below logic if you would like to
track location
(latitude, longitude)
To add Amplitude to your Android Project please follow these steps :
Open your
app/build.gradle
(Module: app) file, and add the following under thedependencies
section :Add the following under
compileOptions
in the android tag :Initialize the Rudder SDK in the
Application
class'sonCreate()
method as following:If you would like to send
Google Advertising Id
of the device asdevice id
to the Amplitude then add the below code in theAndroidManifest.xml
of your app under<application>
tag:Make sure that you enable
Use Advertising ID for Device ID
underAndroid SDK settings
on the dashboard
To add Amplitude to your React Native project:
Add the RudderStack-Amplitude module to your app using :
Open your
android/app/build.gradle
(Module:app
) file, and add the following undercompileOptions
in the Android tag :Import the module added above and add it to your SDK initialization code as shown:
Page
The page
call allows you to record information whenever a user sees a web page, along with the associated optional properties of that page. This method must be called at least once per page load.
A sample page
call looks like the following:
In the above sample, we capture information related to the page being viewed such as the category of the page (Category
), as well as the name of the page (Sample
) along with the unique user ID.
Screen
The screen
method allows you to record whenever a user sees the mobile screen, along with any associated optional properties. This call is similar to the page
call, but is exclusive to your mobile device.
A sample screen
call looks like the following code snippet:
In the above snippet, we capture information related to the screen being viewed, such as screen's name and category.
Track
The track
call allows you to capture any action that the user might perform, and the properties associated with that action. Each action is considered to be an event.
A sample track
call looks like the following:
Revenue events
Amplitude allows for tracking of revenue events.
To track a revenue event, you must include a revenue
key in the event. This key is required to have the event counted as a revenue event to send data through the RudderStack cloud mode.
Additionally, if you send price
and quantity
with the revenue key, the revenue will be calculated in Amplitude as price * quantity
You can also set a product_id
, but only if revenue
has been set as well.
A sample revenue track call looks like the following:
To track revenue event in web device mode, we use Amplitude's logRevenueV2()
api and also for an eCommerce event, we expect revenue
as a top level attribute in properties. If products
array is present in event payload, then to track product individually, at each product level price
or revenue
must be present, or else we will not track the revenue. As logRevenueV2
uses both price
and quantity
to calculate the revenue
, if no quantity
is present, we will take default as 1
.
A sample eCommerce event (Order Completed
) is as following:
The above call will generate one Order Completed
event, 2 individual Product purchased
events and 2 revenue events (one with $price
as 15
and $quantity
as 2
and the other one with $price
as 20
and $quantity
as 1
) at Amplitude, provided that in the destination settings dashboard: Track revenue per product settings
is enabled. The two separate revenue events are generated for device mode. For cloud mode, revenue will be tracked along with the 2 Product purchased
events.
To know more about the difference between Cloud mode and Device mode in RudderStack, read the RudderStack connection modes guide.
(Mobile Only) If a property with the name optOutOfSession
and value true
then this track call will be opted out of the current session if it exists or does not start a new session if there isn't any active session.
Identify
The identify
call lets you associate a user with their actions and capture all the relevant traits about them. This information includes unique userid
as well as any optional information such as name, email address, etc.
A sample identify
call looks like the following:
A sample dashboard after making the above identify
, page
, and track
calls is as follows:
(Mobile Only) If a trait with the name optOutOfSession
and value true
then this identify
call will be opted out of the current session if it exists or does not start a new session if there isn't any active session.
Group
This feature is currently supported by the RudderStack JavaScript SDK only.
Groups are an enterprise-only feature in Amplitude and you need to purchase the Accounts add-on to use them.
The group
call lets you associate a particular identified user with a group, such as a company, organization, or an account.
In order to use the Amplitude groups feature with RudderStack you need to define the Group name trait
and Group value trait
on the dashboard settings pane and you need to pass them as traits while making a group call.
Even if you are not having an enterprise account or groups add-on, RudderStack would add groups
as a User Property
on a user's profile with Group name trait
as its type and Group value trait
as its value.
Let' say you had defined Group name trait
as company_id
and Group value trait
as company_name
and made the above call then the user would be associated with a Group name : RS
and a Group Value : RudderStack
and you can also see that a user property with type RS
and value RudderStack
on user's profile.
Alias
This feature is currently only available when sending events through the JavaScript SDK in the cloud mode.
Refer to the [JavaScript SDK documentation]](https://rudderstack.com/docs/stream-sources/rudderstack-sdk-integration-guides/rudderstack-javascript-sdk/#35-alias) for information and examples on how to call the alias
event.
Mapping
Amplitude's alias
call simply creates a mapping or link between the user_id
specified in the from
parameter to the global_user_id
specified in the to
parameter of the alias
call.
Unmapping
With Amplitude, it is possible to unmap an already established link, or alias
. In order to trigger Amplitude to unmap a connection, follow the code snippet template below.
In the snippet above, user_to_be_unmapped
, will be unmapped or unlinked from the global_user_id
it is currently linked to.
For the unmapping call, it is not necessary to provide a global_user_id
in the to
parameter of the alias
call. If it is included, RudderStack will dismiss it.
For more information on how the alias
call works for Amplitude, visit this link.
Reset
This feature is currently available as a part of RudderStack Mobile SDK's only
The reset method resets the previously identified user and related information. For more information, please refer to our RudderStack API Specification guide.
iOS Android
FAQs
How do I get the Amplitude API Key?
You can find the Amplitude API key in the Amplitude Settings Page.
Why are all my session IDs -1
in Amplitude?
-1
in Amplitude?Session tracking is only supported for the RudderStack device mode because the integration loads Amplitude's SDK. Events sent via the cloud mode connections will have session IDs as -1
.
Contact us
For queries on any of the sections covered in this guide, you can contact us or start a conversation in our Slack community.
Last updated
Was this helpful?