For developers: Getting started

The Amplitude Quick Start Guide walks through the Amplitude data structure and explains which 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'll find technical best practices for getting up and running with Amplitude. For more developer-specific content, check out our Developer Center.

Instrumentation Best Practices

Before getting into the details, let's go over some recommended best practices for instrumenting Amplitude:

• Always test your instrumentation: We highly recommend having a testing project for every production project in your organization. This gives you a reliable way to thoroughly test your instrumentation before sending production data to Amplitude. Amplitude cannot retroactively modify historical data, so if your instrumentation is wrong, the data you collect can't be cleaned up later on. See this video on QA-ing your event data in Amplitude to learn more. 
• Set up at least two Amplitude projects: One for your development or staging environment, one for your production environment. This will keep testing data separate from production data. 
• Send the right keys: If you are sending data server-side via the HTTP API, be sure to send a session_id and insert_id with each event. See this article on ingesting data for more information on these important keys.

How Amplitude receives data

Data can be sent to Amplitude client-side, server-side, or through a third party:

• Amplitude has native client-side SDKs for JavaScript, Android, and iOS. These native SDKs will track the user properties listed here and the session ID for each event for you automatically. SDKs are open source and can be found in Amplitude's GitHub repository.
  There is also a Unity plugin, for use with Unity apps.
• If you'd rather go server-side, the HTTP API will enable you to send data directly from your server to the Amplitude endpoint. Please read through the HTTP API documentation (available at the link above) before instrumenting.
• You can also choose to send us data via a third party like Segment, mParticle, or Tealium. 

Amplitude APIs

Amplitude has numerous APIs you can use in conjunction with the platform:

• HTTP API: Send event data to Amplitude
• Identify API: Update user properties without having to send any additional events
• Dashboard REST API: Export data to be incorporated into Amplitude charts
• Export API: Export all raw event data
• Behavioral Cohorts API: Export behavioral cohorts. 

Amplitude Schema

Amplitude's data structure includes events, event properties, user properties, and group types. If you haven't done so already, you might want to check out our Data Taxonomy Playbook before continuing.

Naming conventions for events

Once you instrument an event, the name of that event type can never be changed in the raw data. For example, let's say in v1.0 of your app, a developer instruments the following event type:

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

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

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

Strings passed to Amplitude are case-sensitive, and so Amplitude will interpret these two event types as completely separate events. Make sure your event names follow a consistent syntax during instrumentation. For more information, see the following section in our Data Taxonomy Playbook.

This also applies to event properties.

Instrumenting User Properties

User properties are attributes specific to individual users. Examples of user properties include location, language, account type, money spent, or player type.

NOTE: For recommendations around which user properties to track, see the Amplitude Data Taxonomy Playbook. 

Amplitude SDKs include 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 the Identify API to update the values of a user's user properties without having to send an additional event. The new values will be applied to the next event sent organically by that user. 

Instrumenting Group Types

NOTE: Group types are only available to Growth and Enterprise customers who have purchased the Accounts add-on. 

To use Amplitude's account-level reporting feature, you will have to instrument group types. Account-level reporting lets you count by a distinct user property group, which in turn enables you to process data at the groups level, instead of the individual users level. Amplitude allows a maximum of five group types. If you're using a third party tool to instrument Amplitude (mParticle, Segment, Tealium), this maximum threshold may be lower based on the partner's limitations. 

How Amplitude tracks unique users and sessions

Amplitude tracks unique users through a system of user IDs, device IDs, and Amplitude IDs. To learn more, check out this article on tracking unique users.

In Amplitude, a session is a single continuous period of time a user is active within your product. Session IDs are sent with every event, enabling Amplitude to track them. To find out more about how this works, see our Help Center article on tracking sessions 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 must be backgrounded before a new session begins
• sessionTimeout (Web): The minimum time between events that must elapse before a new session begins
• batchEvents: This is enabled by default for our mobile SDKs and is optional for Web
• eventUploadPeriodMillis: If batchEvents is enabled, this denotes the time between event batch uploads
• eventUploadThreshold: If batchEvents is enabled, this sets the minimum number of events per batch
• optOut: When enabled, opts the current user out of tracking
• offline: Prevents the sending of events
• saveEvents: This 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 be saved 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. See our Self Data Backfill Guide for detailed instructions on backfilling your data into Amplitude.
2. Your product already has existing users. You want to accurately reflect when these users were new in Amplitude.

Resources

Here are resources you might find helpful during your instrumentation:

• Amplitude Quick Start Guide: This walks 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: This provides best practices on creating a good event taxonomy for your product. 
• Self Data Backfill Guide: See this 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.
• HTTP API: Use Amplitude's HTTP API to send data server-side. 
• SDKs: Use Amplitude's native SDKs to send data client-side.
• Integrations: Find documentation around Amplitude's integrations. For a list of all of our official integrations, see here. 

Video Walkthrough