Getting Started with Amplitude
This article is for developers, and complements the Amplitude Quick Start Guide, which walks through the Amplitude data structure and explains which data you should send to Amplitude.
In this article, you'll find technical best practices for getting up and running with Amplitude.
Instrumentation best practices¶
Before getting into the details, here are some recommended best practices for instrumenting Amplitude:
- Always test your instrumentation: Amplitude recommends having a testing project for every production project in your organization. This gives you a reliable way to test your instrumentation before sending production data to Amplitude
- Amplitude can't retroactively change historical data, so if your instrumentation is wrong, you can't clean up the data you collect later. 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 keeps 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
andinsert_id
with each event. See this article on ingesting data for more information on these important keys.
How Amplitude receives data¶
You can send data 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 track the user properties listed here and the session ID for each event for you automatically. The SDKs are open source and are available 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 enables you to send data directly from your server to the Amplitude endpoint.
- You can also choose to send data via a third party like Segment, mParticle, or Tealium.
Amplitude APIs¶
Amplitude has many 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 an event
- Dashboard REST API: Export the data used in Amplitude charts
- Export API: Export all raw event data
- Behavioral Cohorts API: Export behavioral cohorts.
See all the API references.
Amplitude schema¶
Amplitude's data structure includes events, event properties, user properties, and group types.
Data Taxonomy Playbook
Our Data Taxonomy Playbook can help you understand more about the Amplitude schema, and Amplitude recommends reading it before continuing.
Naming conventions for events¶
After you instrument an event, you can never change the name of that event type in the raw data. For example, 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 interprets these two event types as separate events. Make sure your event names follow a consistent syntax during instrumentation. For more information, see this section in the Data Taxonomy Playbook.
This also applies to event properties.
Instrument user properties¶
User properties are attributes specific to individual users. Examples of user properties include location, language, account type, money spent, or player type.
Data Taxonomy Playbook
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 valuesetOnce
: Set the value only if the value hasn't already been setunset
: Unset the value tonull
add
: Increment the numerical value by a specified numberappend
: Append the value to the property arrayprepend
: 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 another event. The new values are applied to the next event sent organically by that user.
Instrument group types¶
Feature availability
This feature is available in accounts with a Growth or Enterprise plan with the Accounts add-on.
To use Amplitude's account-level reporting feature, you 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 the 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 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 the SDKs, and allows the SDK to save unsent events onto the device.savedMaxCount
: The maximum number of unsent events that are saved on a device. The default is 1000.
Backfilling data¶
You may want to consider backfilling data if:
- You wish to analyze historic data in Amplitude. See the Data Backfill Guide for detailed instructions on backfilling data into Amplitude.
- 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.
- 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. See all Amplitdue's official integrations.
Instrumentation seminar video¶
This video is an instrumentation seminar aimed at developers.