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. For example, "age" can be a user property. 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.
Table of Contents
- User Properties
- Event Properties
- Hiding Properties
User properties are attributes of the user and are sent with every event. Properties intrinsic to the user, such as age or gender, 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 age, gender, email, locale, referral source, plan type, number of friends, or current level in a game. '[Amplitude]' will appear next to user properties that our SDK tracks automatically. Custom user properties that you choose to track will not have '[Amplitude]' prefixed.
Amplitude tracks the following user properties by default from our SDKs:
- Device Type
- Device Family
- Start Version
You can find the definitions of each property here.
Additional Notes: 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 for JS SDK here, Android SDK here, and iOS SDK here. These configurations will prevent default properties from being tracked on newly created projects, where data has not yet been sent. Please contact firstname.lastname@example.org 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.
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. User properties will not apply retroactively and so once set they will only be applied to all events received by Amplitude going forward. 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, if a user has the user property 'SongsPlayed' = '45' and a few minutes later they perform 'PlaySong' again, then 'SongsPlayed' will now equal '46'. 'SongsPlayed' will equal '46' for all future events until the property is updated again.
At 4:30pm, 'PlaySong' was fired with 'SongsPlayed' = 45.
At 4:04pm, 'PlaySong' was fired with 'SongsPlayed' = 46.
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 segment on "most recent" properties 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 that a value of none 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 an event level.
Similarly, the CSV download from any chart will display the user's most recent user property values. This does not always mean this was the user's value at the time they performed the event in 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 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'.
Some example event properties are description, category, type, duration, level, % completed, count, source, status, number, lives, authenticated, error number, rank, action, and mode. Leverage event properties to reduce the number of events you are tracking and/or better analyze your events.
You can hide old or buggy properties in your project's Settings page. Hiding event or user properties will only hide them from appearing on the platform UI and does not delete them. You can always unhide the properties.