Properties are attributes that provide additional context around your users and the events they trigger. There are two types of properties in Amplitude:
- User properties: User properties are attributes of the users and reflect the current state of the user. They are useful because it is possible for user properties to change over time and as such, these properties would not be unique to events and are instead tied to the user.
- Event properties: Event properties are attributes of a particular event and reflect the state at which the event was triggered. For the event 'JoinCommunity', an event property could be 'Type' which denotes the type of community joined at the time of that event. A user can join a pop community, rock community, and jazz community, and this data is specific to each of those 'JoinCommunity' events. The type of community joined provides more information about the specific event as a user can join many different types of communities.
Overview
This is part of our Getting Started with Amplitude Series! You are currently on Part 5 of 7 in the series: User & Event Properties. We are invested in your success and wrote this guide to help you set up Amplitude in the quickest and most optimal manner. This Quick Start Guide will walk through the data structure and what data you should send to Amplitude. Specifically, it will cover:
Important Note:
- Must have the most updated Amplitude JS SDK (version 4.7 or higher) implemented.
- The Amplitude JS SDK must be placed above the Optimizely snippet.
- Introduction & Getting Started
- Instrumentation Pre-Work: what you should think about before deciding what data to send
- Identifying Users: what is required to properly track unique users for your product
- Event Data: what events or user actions you should track
- User Properties & Event Properties: what attributes you should send to upscale your analytics
- Cross Platform Instrumentation vs. Separate Platform Instrumentation: when you should do either way of instrumentation
- Using the Amplitude Platform: helpful definitions
If you are a developer or product manager who will be responsible for instrumenting Amplitude, then you should also read our Getting Started Guide for Developers as well.
For more detailed recommendations and best practices on what user and event properties to track, check out our Data Taxonomy Playbook.
Table of Contents
User Properties
These reflect traits about an individual person using your app. User properties are attributes of the user and are sent with every event. Properties intrinsic to the user should be set as user properties. These reflect traits about an individual person using your product. Some examples of custom user properties you can send Amplitude are locale, referral source, plan type, number of friends, or current level in a game. '[Amplitude]' will appear next to user properties that our SDKs track automatically. Custom user properties that you choose to track will not have '[Amplitude]' prefixed.
The most important thing to remember is that these user properties reflect the state of the user and apply across all of their events moving forward until the properties are updated again. You also do not need to send custom user properties with every event. Previous user properties are attached to an event until they are updated. Do not worry if you forget to apply custom user properties to your events, as you can always go back and update user properties at a later point using our Identify API.
Amplitude tracks the following user properties by default from our SDKs:
- Platform
- Device Type
- Device Family
- Country
- City
- Region
- Start Version
- Version
- Carrier
- OS
- Language
- Library
You can find the definitions of each property here.
Important Note:
- IP Address is also collected by default. If you do not wish for any of the default properties to be tracked, please disable tracking in your SDK configuration. Details can be found for our JS SDK, Android SDK, and iOS SDK. These configurations will prevent default properties from being tracked on newly created projects, where data has not yet been sent.
- Please contact our Support team at support.amplitude.com if you would like default properties blocked (moving forward) on projects with existing data.
- Our customers typically implement at most 20 user properties on top of what Amplitude automatically tracks. We recommend discussing user properties with your dedicated Success Manager if you plan to implement more than 20 user properties.
Updating User Properties
User properties reflect the state of the user and apply across all of their events moving forward until the properties are updated again. You do not need to send custom user properties with every event; once a user property is set, the set value will persist and be applied to all subsequent events until the value is changed. Do not worry if you forget to apply custom user properties to your events, as you can update user properties at a later point using our Identify API.
When a user property changes, all subsequent events will be associated with the new user property. For example, the user property, 'Playlists' records their preferred playlists on September 24th, but they update their preferred playlists on September 27th, that user property will remain as [95, 106,78,144,168] for all future events until they update their preferred playlists again.
On September 24th, 'Playlists' was:
On September 27th, they updated their preferred playlists to:
Furthermore, the top of a user's activity page will display the most recent user properties. The user properties displayed with each event in a user's individual event stream capture the value of the user property at the time of the event.
On the day a user property changes, the user will be counted as having been in both the old user property category and new user property category. For example, let's say on July 1 a user logs into your game app version 1.0 and plays a few games. On the same day, she updates the app to version 2.0 and plays some more. If you segment the daily active user graph by version and compare version 1.0 and 2.0, then that particular user would appear as a user in both segments (unless you select the "Most Recent Value" option in our User Composition chart). However, on July 2 and onwards she would only appear in the version 2.0 segment until she updates to a newer version.
When applying a user segment to a chart, the chart will show '(none)' values if the user had a value of '(none)' for a property at the time of the event. So, if a user initially had 'isPaying' = '(none)' for their first 'PlaySong' event and later had 'isPaying' = 'False' for the next 'PlaySong' event, then the user will show up in both buckets. However, when you look at the User Activity page, their most recent value for that property will show up because you are now looking at the data at a user level and no longer at a event level.
Similarly, the CSV download from any chart will display the user's most recent value. This does not always mean this was the user's value at the time they performed the event on the chart, and so it is likely these values will be different from the chart.
Applying User Properties to Events
User properties are applied in the following order:
- User property is updated before an event (say Event-A) is sent: The property's value is updated in the user property table, and it is reflected in the UI when Event-A is sent to Amplitude.
- If the Identify API is used, the updated value is reflected in the UI when Event-A is sent to Amplitude.
- User property is updated after an event (say Event-A) is sent: Event-A is sent to Amplitude, and then the property's value is updated in the user property table. The updated value is not reflected in the UI until another event is sent, and it does not get applied to events retroactively.
- If an Identify call is sent after Event-A, the updated value is not reflected with Event-A. It will be reflected in the UI when another event is sent after the Identify call.
- User property is sent with an event (say Event-A): For events sent via our HTTP API, you can include user properties with the server-side call. The updated user property value is reflected in the UI as soon as Event-A is received by Amplitude; the user property table is also updated upon Event-A's ingestion. Future events will have the updated user property value until the value in the user property table is updated again.
Therefore, in order for a new user property value to be reflected in the UI, an event must follow or be sent with the update. You can also use the Identify API to update user properties, but updates this way still follow the same above logic. Please read and understand the Identify API documentation fully before using it.
Event Properties
Event properties are attributes of events and each particular event will have its own set of event properties. These properties highly depend on the type of product you have and the specific information you think is necessary to better understand a specific event. For instance, if 'Swipe' is an event that you are tracking, then the event property ‘Direction’ could have the values ‘Left’ or ‘Right’.
These properties highly depend on the type of app you have and the specific information you think is necessary for understanding a particular event.
General keys we have seen are cause, description, category, type, duration, level, % completed, name, count, source, status, from, number, lives, authenticated, error, rank, action, and mode. Leverage event properties to reduce the number of events you are tracking.
Sending Data to Amplitude
Find specific information on how to send data to Amplitude here:
- Amplitude SDKs: Find our list of SDKs here.
- Amplitude HTTP API: Use our HTTP API to send server-side event data.
- Segment.io: See Segment / Amplitude Integration for more information.
- mParticle: See mParticle / Amplitude Integration for more information.
Step 5: Cross Platform Implementation vs. Separate Platform Implementation