In Amplitude, 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 the attributes of individual users. Common user properties include device type, location, User ID, and whether the user is a paying customer or not. An attribute can reflect either current or previous values, depending on its nature and how often it is updated.
- Event properties: Event properties are attributes of a particular event. The values they contain are current for the moment at which the event was triggered. For example, the event
JoinCommunitycould have an event property of
Type, which denotes the kind of community joined at the time of that event.
This article will describe what user and event properties do, how Amplitude updates and applies them, and how you can hide individual properties in an Amplitude project.
As mentioned above, a user property is an attribute that describes a useful detail about the user it's attached to. Amplitude sends user properties with every event.
Amplitude's SDKs track the following user properties by default:
- Device Type
- Device Family
- Start Version
- IP Address
You can find the definitions of each property here.
You can also set up custom user properties. Be sure to choose characteristics and traits that are intrinsic to the user or to the device they're using; otherwise, the data you collect from your user properties won't be as useful. Some common examples of custom user properties include referral source, plan type, number of friends, or current level in a game.
You can tell the difference between default Amplitude user properties and custom user properties by looking for the Amplitude logo. If you see it, you've located a default user property. The names of custom user properties will not be prefixed by that logo.
Amplitude customers typically implement up to 20 custom user properties, in addition to the default properties.
How Amplitude updates user properties
When a user fires an event that is captured by Amplitude, it includes the current values for each user property, but these values can change over time. For example, a user might relocate from New York to Dallas, or convert from a free user to a paying one. When this happens, Amplitude updates the user properties and applies the new values to the events the user sends from that point forward. Updates to user property values are not applied retroactively and the older values are maintained in your historical data. In other words, the property values should always reflect the values at the time of the event.
For example, in the image below, this user joined a community at 10:12 am. The value for the
Communities_Joined property became 448.
This user also joined a community about a week earlier, on September 21st, at 7:54 pm. When that event is selected, the
Communities_Joined property is shown as 447—which was the value at the time that the
Join Community event was fired.
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. This information is derived from either the most recent event sent via an Identify call.
NOTE: You do not have to send custom user properties with every event. Once a user property is set, its value will persist, and Amplitude will apply it to all subsequent events until the value is changed. Don't worry if you forget to apply custom user properties to your events, as you can update user properties later via the Identify API, however note that if you query on this event in Amplitude later, the updated user property will not appear with the event and will only apply to events from that point forward.
When old and new user property values overlap
When a user property's value changes, Amplitude charts can show the user in both the new and the old user property categories. This overlap only applies for the specific day on which the property value changed.
Here's an example of how that might work: On July 1st, a user logs into your game app—currently at version 1.8—and plays a few games. Later that day, she updates to the brand-new version 2.0 and plays some more. If you segment the daily active user chart by version, and then compare version 1.0 and 2.0, that user will appear in both segments for that day. However, beginning July 2nd, she'll only appear in the version 2.0 segment, until she updates to a newer version.
Something similar can happen when you've applied a user segment to a chart. Amplitude will show
(none) values if the user had no value for a user property at the time of the event. If a user initially had
(none) for their first
PlaySong event, but then had
True for the next
PlaySong event, the user will show up in both buckets. If you look at the User Activity page for that user, only their most recent value for that property will appear in the top section of their profile.
How Amplitude applies user properties to events
User properties can be applied to events in three different ways:
- User property is updated before an event is sent: The property's value is updated in the user property table and is applied to the next event that is sent to Amplitude. This is the recommended and expected method for updating user properties so that the updated property value is correctly applied to the event.
- User property is updated after an event is sent: The event 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.
- If an Identify call is sent after the event, the updated value is not reflected with the event. It will be reflected at the top of a user's profile, but will not appear in chart results until another event is sent after the Identify call.
- User property is sent with an event: For events sent via Amplitude's 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 the event is received by Amplitude; the user property table is also updated once the event is ingested. Future events will have the updated user property value until the value in the user property table is updated again.
For a new user property value to be reflected in the UI, an event must follow or be sent with the update. User properties can be updated via the Identify API. Please read and understand the Identify API documentation fully before using it.
Event properties are attributes of the events your users fire, and which you then send to Amplitude. Each event will have its own set of event properties. The nature of these properties depends on both the type of product you have, and the specific information you're most interested in discovering. For instance, if
Swipe is an event you're tracking, the event property
Direction could have the values
Some example event properties are description, category, type, duration, level, percent completed, count, source, status, number, lives, authenticated, error number, rank, action, and mode. Use event properties to reduce the number of events you're tracking and/or better analyze your events.
You can hide old or buggy properties in your project's Govern 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 if you change your mind.