On this page

Getting started with Amplitude

This article describes technical best practices for getting up and running with Amplitude.

Instrumentation best practices

Follow these recommended best practices when instrumenting Amplitude:

  • Always test your instrumentation: Amplitude recommends having a testing project for every production project in your organization. A testing project 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.
  • Set up at least two Amplitude projects: One for your development or staging environment, and one for your production environment. Two projects keep testing data separate from production data.
  • Send the right keys: If you send data server-side with the HTTP API, send a session_id and insert_id with each event.

How Amplitude receives data

You can send data to Amplitude through SDKs or through a third party:

Amplitude APIs

Amplitude has many APIs you can use with the platform.

Refer to all the API references.

Amplitude schema

Amplitude's Data Planning Playbook can help you understand the Amplitude schema. 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, in v2.0 of your app, a developer instruments this event type:

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

Strings passed to Amplitude are case-sensitive, so Amplitude interprets these two event types as separate events. Make sure your event names follow a consistent syntax during instrumentation.

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.

For recommendations on which user properties to track, refer to 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 only if the value isn't already set.
  • 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 sending another event. The new values apply to the next event the user sends organically.

Instrument group types

To use Amplitude's account-level reporting feature, instrument group types. Account-level reporting lets you count by a distinct user property group, which lets you process data at the groups level instead of the individual users level. Amplitude allows a maximum of five group types. If you use a third-party tool to instrument Amplitude (mParticle, Segment, Tealium), this maximum threshold might 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, refer to tracking unique users.

In Amplitude, a session is a single continuous period of time a user is active within your product. Session IDs send with every event, which lets Amplitude track them. For more information, refer to tracking sessions in Amplitude.

This section details Amplitude SDK configuration options that users commonly modify.

  • 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: Enabled by default for mobile SDKs and optional for Web.
  • eventUploadPeriodMillis: If batchEvents is enabled, this option sets the time between event batch uploads.
  • eventUploadThreshold: If batchEvents is enabled, this option 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: Enabled by default for all SDKs. Lets the SDK save unsent events onto the device.
  • savedMaxCount: The maximum number of unsent events saved on a device. The default is 1000.

Backfilling data

Consider backfilling data if:

  1. You want to analyze historic data in Amplitude. For detailed instructions on backfilling data into Amplitude, refer to the Data Backfill Guide.
  2. Your product already has existing users. You want to accurately reflect when these users were new in Amplitude.

Was this helpful?