User attributes
What Amply knows about a user. Attributes come from three places: the device itself, the app install, and what your code tells Amply. Targeting rules, frequency caps, and campaign conditions are all built on top of these.
Three sources of attributes
Device attributes
The SDK, automatically
Platform, OS version, country, device model
App attributes
The SDK, automatically
Install date, app version at install, current app version
User attributes
You, from app code
User ID, plan tier, premium status, account age
You rarely think about the boundary when you are writing rules in the dashboard — the rule builder shows all three groups together. But it helps to know which is which when you are asking "can I target on this?"
Device attributes — automatic
The SDK collects these from the platform. You do not need to write any code.
Platform — iOS or Android.
OS version — the operating system version.
Country — derived from the device locale.
Application — which of your apps this is (relevant for projects with more than one app).
Device attributes describe the environment. They are good for rolling out a campaign only on one platform, or gating on a minimum OS version.
App attributes — automatic
These describe the install and the usage.
Install date — when the app was first installed on this device.
App install version — the app version at install time. Useful for distinguishing long-time users from recent installs.
App version — the app version currently running.
App attributes describe the user's relationship to your app over time. They let you ask "is this a brand-new user or a returning one?", "which cohort did they install into?"
Note — session count. The SDK tracks session count internally, but it is not currently exposed as a built-in targeting attribute in the rule builder. To target on session count, set it as a custom property from your app on every session start — see Sessions and events.
User attributes — you set these
This is the only group your code controls. There are two calls you need to know:
setUserId(userId)— attach a stable identifier to this device. Call it when the user logs in. Call it withnullto clear on logout.setCustomProperty(key, value)— store a named value for this user. Call it whenever the value changes.
Custom properties take primitive values. The SDK supports strings, numbers, and booleans on every platform. The iOS and Android native SDKs additionally support date/time values. Nested objects and arrays are not supported — keep values flat.
Examples of custom properties worth setting:
plan— "free", "pro", "team"premium— true / falsetrial_ends_at— a datesignup_source— "organic", "paid_ads", "referral"account_tier— 1, 2, 3
Custom properties are the bridge between your app's internal state and Amply's targeting. If you want to target "users on the pro plan", someone has to call setCustomProperty("plan", "pro") when the user's plan becomes pro.
When to use which
You want to roll out to a platform or OS → device attribute.
You want to gate on "how long have they used the app" → app attribute (install date) or a custom property (session count, time-in-app).
You want to gate on a product concept your app owns (subscription state, account type, premium tier, experiment cohort) → user attribute (custom property).
Rule of thumb: if the value lives inside your app's business logic, it is a custom property. If it comes from the device or the install, the SDK has it for free.
Identifying the same user across installs
setUserId is how you keep targeting stable when the user reinstalls, moves devices, or logs in on a second device. The device is what Amply sees by default; setUserId gives you a stable handle on top of that.
Set the user ID as soon as you have one. Clear it (pass null) on logout so the next user on the same device does not inherit the previous user's properties.
Custom property lifecycle
Custom properties persist on the device. Once you set a property, it stays until:
You call
setCustomPropertyagain with the same key (overwrite).You call
removeCustomProperty(key)(delete one).You call
clearCustomProperties()(delete all).The user uninstalls the app.
The persistence means you do not need to re-set properties on every app launch. Set them when they change.
React to a property changing
Targeting on a custom property answers "who is this user right now." But sometimes the moment of change is the opportunity. Every time a custom property is set, updated, removed, or cleared, Amply emits a CustomPropertyChanged event — and you can use that event as a campaign trigger.
That means you can react to the instant a trait flips, not just to its current value. For example, fire a winback the moment plan_tier becomes free — the change itself is the signal, so the campaign runs at exactly the right beat instead of waiting for the next session or event. The event carries the property key plus its old and new value, so a trigger can condition on the direction of the change. See Events for the exact parameters.
See Tracking events for event tracking, and User attributes (dev) for the exact signatures.
What is already there vs. what you have to set
Platform
yes
iOS / Android
OS version
yes
Country
yes
derived from locale
App version
yes
current version
App install version
yes
the version at install time
Install date
yes
first install
Session counter
tracked but not targetable
set as a custom property if you need to target on it
User ID
no
call setUserId on login
Custom properties
no
call setCustomProperty whenever values change
Related
Targeting and audiences — how attributes become rules
Sessions and events — the other half of what Amply knows
User attributes (dev) — SDK calls in code
Tracking events — complementary: events describe behavior, attributes describe identity
Last updated