Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Targeting and audiences

How Amply decides who sees what. A campaign reaches a user only when that user matches the campaign's conditions. This page explains the vocabulary: rules, operators, audiences.

Rules are built from conditions

A rule is a list of conditions you combine in the rule builder. Each condition compares one attribute against one value using one operator.

Plain example:

Users whose country is France AND whose subscription_status equals premium AND who installed the app in the last 30 days.

That is three conditions joined with AND. Each condition follows the same shape:

<attribute>           <operator>          <value>
country               equals              France
subscription_status   equals              premium
install date          is less than        30 days ago

You build this in the dashboard's rule builder by adding conditions one at a time. Conditions are joined with AND — every condition must pass for a user to match. Within a single condition, list-style operators give you an internal OR — "country is one of France, Germany, Italy" matches a user in any of the three.

Attributes you can target on

Attributes are grouped by where they come from. See User attributes for the full picture; here is what you can use in targeting conditions today:

  • Country — the device's country.

  • OS version — the device OS version (for example, iOS 17).

  • App version — the current app version installed on the device.

  • App install version — the version of the app at install time (useful for "only users who installed after v3.0").

  • Application — which app in your project (include or exclude a specific app).

  • Install date — when the user first installed the app. Works as an absolute date ("installed after 2026-01-01") or a relative one ("installed in the last 7 days").

  • Event history — what the user has actually done in your app: how many times they've performed an event, whether they've ever done it, and when they first or last did it. Optionally narrowed by event properties ("Purchase where product equals pro"). See Targeting on past behavior below.

  • Custom properties — values you set on the user from your app code (plan tier, premium status, internal user type).

For the full list and when to use which, see User attributes.

Operators

The operator set changes slightly by attribute type, but the vocabulary is small.

Numeric and version comparisons:

Operator
Meaning

equals

exactly equal

not equal

anything but this value

greater than

strictly greater

less than

strictly less

greater or equal

greater than or the same

less or equal

less than or the same

Existence checks:

Operator
Meaning

is set

the user has a value for this attribute

is not set

the user has no value

List membership (for country, application):

Operator
Meaning

include

match when the user's value is in the list

exclude

match when the user's value is NOT in the list

Dates:

Dates support absolute ("on or after 2026-01-01") and relative ("in the last 30 days") forms. Absolute comparisons work in whole calendar days (UTC) — "install date is 2026-01-01" matches any moment during that day. Relative comparisons count rolling 24-hour windows back from now, not calendar days — "in the last 7 days" means the last 168 hours.

Audience — the result of a rule

An audience is the set of users who currently match a rule. It is not a stored list. It is evaluated on-device every time a campaign is considered, using the latest attributes. A user who was in an audience yesterday can drop out today (for example, the user updated to a new app version, or changed country on vacation).

This matters: audiences are live. You do not "refresh" or "rebuild" them. A campaign that says "users in France on app version ≥ 5.0.0" will immediately pick up a French user the moment they upgrade.

Targeting on past behavior

Audience rules can target events directly. An Event condition matches users by what they have done since installing the app — no extra code, no custom property to maintain.

An Event condition can check three things, alone or combined:

  • How many times. "Did Purchase at least 3 times", "did WorkoutCompleted fewer than 5 times". Operators: exactly, not exactly, more than, fewer than, at least, at most — plus the simple forms has happened (ever) and has never happened.

  • When — first or last occurrence. Relative: "last WorkoutCompleted was more than 14 days ago" (with an explicit "…or never" variant) or "first Purchase was within the last 7 days". Absolute: before or after a specific date. Absolute dates cover whole calendar days (UTC); relative "days" are rolling 24-hour windows, not calendar days.

  • With matching properties. Narrow the condition to occurrences whose properties match — "Purchase where product equals pro". Comparisons: equals or not equals; number values also support greater and less. Only matching occurrences count, both for counts and for first/last dates.

Event history starts at install, and Event conditions behave like every other condition: evaluated on the device, live, joined with AND, and working offline.

Event conditions require apps built with SDK 0.6.1 or later. On older app builds, a campaign that uses an Event condition simply never matches — nothing breaks, the campaign just stays silent for those users.

When a custom property still fits

For derived state that isn't a single event — a computed status, a combination of several signals, or something your backend decides — set a custom property on the user and target that instead. The rule builder targets on the property; the event is the trigger that lets your code set it.

When your backend flags an account as at-risk, call setCustomProperty("account_status", "at_risk"). A campaign for those users targets account_status = "at_risk" — something no single event count could express.

Either way, the result is a rich audience composed of attribute, event, and property conditions, all joined with AND. See Campaign delivery for how triggers then decide when the campaign actually fires for those users.

Targeting vs. triggering

These are often confused.

  • Targeting decides who is eligible. "Is this user a match for this campaign?"

  • Triggering decides when the eligible user sees it. "Has the right thing just happened?"

A user can be targeted by ten campaigns but only one triggers on any given event. See Scenarios and campaigns and Campaign delivery for how the two layers interact.

Practical examples

  • "France or Germany, premium users" — country IN [France, Germany] AND custom property plan = "premium".

  • "New users on the latest app version" — install date in the last 7 days AND app version >= 3.4.0.

  • "Lapsing premium users" — custom property plan = "premium" AND custom property trial_ends_at is within the next 3 days.

  • "Users who never finished onboarding" — OnboardingCompleted has never happened (or, if you also maintain a property: has_onboarded is not set / equals false).

  • "Repeat buyers" — did Purchase at least 3 times.

  • "Lapsed workout loggers — win-back" — last WorkoutCompleted was more than 14 days ago.

  • "Never tried export" — ExportClicked has never happened.

Related

PreviousSessions and events
NextUser attributes

Last updated