For Developers: Getting Started

Updated

The Amplitude Quick Start Guide walks through the Amplitude data structure and what data you should send to Amplitude. This article is meant to complement the Quick Start Guide and is specifically meant for developers who will be instrumenting Amplitude. In this article, you will find technical best practices on how to get up and running with Amplitude.

Table of Contents

 

Sending Data to Amplitude

Customers can send data from sources such as phones, browsers, and servers. After data is sent to Amplitude's event servers, Amplitude will process and store the data.

Screen_Shot_2017-08-04_at_2.55.31_PM.png

Data can be sent to Amplitude client-side, server-side, or through a third party. Each of these methods is outlined below.

 

Client-Side

Amplitude has native SDKs for JavaScript, Android, and iOS. Amplitude also has an Unity plugin that can be used for Unity apps. All of the SDKs are open source and can be found in Amplitude's GitHub repository. Installation guides for each of the SDKs are linked below.

Amplitude's native SDKs will track the user properties listed here and the Session ID for each event for you automatically. 

 

Server-Side

You can send data to us server-side through our HTTP API. This will allow you to send data directly from your server to our endpoint. Please read through the important notes of the HTTP API to avoid complications.

 

Technology Partners

You can also choose to send us data through Segment, mParticle, or Tealium. 

 

Amplitude Schema

This section will cover Amplitude's data structure. This includes events, event properties, user properties, and group types.

 

Instrumenting Event Types & Event Properties

An event is an action that a user performs in your product that you wish to track. However, you can also choose to send server-side events for data that cannot be collected client-side (e.g. 'send email'). When you instrument events, keep in mind that naming convention is important. Once instrumented, the name of an event type can never be changed in the raw data. For example, let's say in v1.0 of your Android app a developer instruments:

Amplitude.getInstance().logEvent('Play song');

Later on, in v2.0 of your app, a developer instruments:

Amplitude.getInstance().logEvent('play song');

Strings passed to Amplitude are case-sensitive, and so these two event types will be treated as completely different events. Thus, it is crucial to ensure that event names follow a consistent syntax during your instrumentation. For more information on best practices on event type nomenclature, see the following section in our Data Taxonomy Playbook.

Event properties are attributes that are specific to a certain event type. For example, for the 'play song' event you can track 'song name' as an event property. Similar to event types, naming matters here as well. You can find more information around event properties here in our Data Taxonomy Playbook. 

 

Instrumenting User Properties

User properties are attributes specific to each user in your product. This can be information such as age, account type, or player type. If you are sending data client-side, then Amplitude will track these user properties automatically for you. For recommendations and best practices on what user properties to track, see this section in our Data Taxonomy Playbook. 

The order in which you set user properties matters and when you query on the value of a user property, you are querying on the value at the time of the event. This is because user properties are applied to events by attaching them to a user's events as they are received by Amplitude's servers. So, once a user property has been set for a particular user, then all of a user's events going forward will contain that user property. For example, let's say you want to track each user's 'favorite genre' but you do not know the value of that user property until they create their profile in your product. Before logging the 'create profile' event, you should set the user's 'favorite genre' user property since you know that information once a user has created their profile. The 'create profile' event and all events going forward will contain the 'favorite genre' user property and you will be able to segment on that user property. However, the 'favorite genre' user property will not be set on all events before the 'create profile' event since at the time of those events you do not know the user's favorite genre yet. As a result, the value will be null if you attempt to query the 'favorite genre' user property on events triggered before the 'create profile' event. For more information on how user properties are applied to events, see here. 

Amplitude SDKs also has several user property operations you can use to update user property values:

  • set: Set or overwrite the property value.
  • setOnce: Set the value, and once set these values cannot be overwritten.
  • unset: Unset the value to null.
  • add: Increment the numerical value by a specified number.
  • append: Append the value to the property array.
  • prepend: Prepend the value to the property array.

You can also use our Identify API to update user properties. This will allow you to update the values of a user's user properties without having to send an additional event in order to update them. The new values will be applied to the next event that user sends organically. 

 

Instrumenting Group Types

Note: Group types are only available to Enterprise customers who have purchased the Accounts add on. 

To utilize Amplitude's account-level reporting feature, you will have to instrument group types. Account-level reporting allows you to count by a distinct user property group, allowing you to process data by group instead of by individual user. Amplitude allows a maximum of 5 group types. If you are using a third party to instrument Amplitude (mParticle, Segment, Tealium), then this maximum threshold may be lower based on the partner's limitations. 

 

User Identification

Amplitude uses a system of User IDs, Device IDs, and Amplitude IDs to track unique users. For more detailed documentation on this system, see our article here.

 

User ID

A User ID is a unique identifier for each user that cannot change and is optional. Note: A user can only have one User ID and if it is changed, then Amplitude will treat that new User ID as a different user. It is fine to not set a User ID--you should not set a User ID for anonymous users. On the other hand, we strongly suggest setting a User ID once the user has created an account, logged in, or is otherwise identified in your product.

 

Device ID

Every event requires a Device ID, which is a customizable unique identifier for a device. Amplitude's native SDKs will generate a Device ID for you automatically. If you are sending data server-side and you do not set a Device ID, then we will hash the User ID sent with the event and turn it into a Device ID. 

 

Amplitude ID

An Amplitude ID is an unique identifier for unique users. This is generated by Amplitude based on User ID and Device ID at the time of ingestion.

 

Merging Users

Amplitude can merge users together if events triggered under an anonymous user are later linked to a user with a User ID. For example, let's say we have a user Bob who upgrades his phone. His original phone that has our app installed has a Device ID of A. He creates an account and is assigned a User ID of Bob with an Amplitude ID of 1. When Bob upgrades to a new phone, his Device ID changes to B and he is assigned an Amplitude ID of 2 (because the Device ID is completely different). When he signs in on his new device, Amplitude will recognize that Bob is the same person and will map Amplitude ID 2 to Amplitude ID 1. This way, all of Bob's events will be recognized under the same user in Amplitude even though he is on 2 different devices. To read more about merged users and to see more examples, see here. 

Screen_Shot_2017-08-15_at_3.14.16_PM.png

 

Tracking Sessions

A session is a period of time the user is active within your product. A Session ID will be sent with every event and it will be set to the start time of the session in milliseconds since epoch (Unix Timestamp).

For example, 1501581600000 is equivalent to August 8th, 2017 10:00:00AM UTC. All events in the same session will share the same Session ID. If you wish to exclude events from your session calculations (e.g. events like 'push notification sent' or 'email opened'), then you can set the Session ID to -1. Amplitude's SDKs will automatically track sessions. If you are sending us data server-side, then you will need to manually set the Session ID. Otherwise, the Session ID will default to -1 and all server-side events will be treated as out-of-session events. See the documentation here to learn more about session tracking in Amplitude. 

 

Popular SDK Configuration Options

This section details some Amplitude SDK configuration options that are popularly modified.

  • minTimeBetweenSessions (iOS/Android): The minimum time your app has to be in the background to start a new session.
  • sessionTimeout (Web): The minimum time between events to start a new session.
  • batchEvents: This is enabled by default for our mobile SDKs and is optional for Web.
  • eventUploadPeriodMillis: If batchEvents is enabled, this option denotes the time between event batch uploads.
  • eventUploadThreshold: If batchEvents is enabled, this option sets the minimum number of events per batch.
  • optOut: Whether or not to opt the current user out of tracking.
  • offline: This option prevents the sending of events.
  • saveEvents: This option is enabled by default for all of our SDKs, and will allow the SDK to save unsent events onto the device.
  • savedMaxCount: The maximum number of unsent events to save on a device. The default is 1000. 

 

Backfilling Data

You may want to consider backfilling data if:

  1. You wish to analyze historic data in Amplitude. You can utilize our Self Data Backfill Guide to backfill your data into Amplitude. Please see our Self Data Backfill Guide for detailed instructions on how this can be accomplished.
  2. Your product already has existing users. You want to accurately reflect when these users were new in Amplitude. Note: A user is considered new the day of their earliest event in Amplitude.

 

Instrumentation Best Practices

1. Always test your instrumentation. We highly recommend having a testing project for every production project in your organization. This way, you can thoroughly test your instrumentation before sending production data. Historical data cannot be retroactively modified, and so it is imperative that you have clean instrumentation. See here for a video on how to QA your event data in Amplitude. 

2. Set up at least two Amplitude projects. One for your development or staging environment and one for your production environment. This will allow you to keep testing data separate from production data. You should always thoroughly test your instrumentation before sending data to your production project.

3. HTTP API best practices. If you are sending us data server-side via the HTTP API, be sure to send a session_id and insert_id with each event. See here for more information on these important keys.

 

Amplitude APIs

Amplitude has numerous APIs that you can leverage in addition to the platform.

 

Resources

Here are resources you might find helpful during your instrumentation.

  • Amplitude Quick Start Guide: This Quick Start Guide will walk through the setup process to get your first project up and running. It also provides helpful tips to get started on building an event taxonomy.
  • Data Taxonomy Playbook: For best practices on how to come up with a good event taxonomy for your product, see our Data Taxonomy Playbook. 
  • Self Data Backfill Guide: See our Self Data Backfill Guide for detailed instructions on how to backfill historical data into Amplitude.
  • Validating Event Data: This article walks through best practices on validating your instrumentation in Amplitude and also includes a video.
  • Learning Center: Our Learning Center has articles on each Amplitude feature.
  • HTTP API: Use our HTTP API to send us data server-side. 
  • SDKs: Use our native SDKs to send us data client-side.
  • Integrations: Find documentation around our integrations. For a list of all of our official integrations, see here. 
  • Instrumentation Training Seminars: Register for one of our instrumentation training seminars!

 

Video Walkthrough

 
Was this article helpful?
6 out of 6 found this helpful
Have more questions? Submit a request
Return to top

Related articles