Targeted Rollout
What Targeted Rollout Is
Targeted rollout lets you limit a rollout to users who match specific user property rules.
It is used together with Staged Rollouts, but it is optional. Targeted rollout acts as an extra gate before the rollout percentage is applied.
It does not replace Managed Publishing or staged rollout. It only narrows the audience after those controls are already in place.
Targeted rollout is configured from the staged rollout flow on a channel's Bundles page.
How It Works
At a high level:
- In the dashboard, you define the user property keys your project uses on the project's User Properties page (e.g.
tier,country,role). - In your app, you set key-value pairs for those properties based on your product logic (e.g.
tier = "premium",country = "US"). - When configuring a rollout, you enable targeted rollout and add one or more targeting rules. Each rule specifies a property key and one or more allowed values.
- When a device checks for updates, Bundle Drop evaluates the rules against the device's current properties. If any rule matches, the device is eligible.
- After that, the rollout percentage is applied to the matched group.
Examples:
- targeted rollout on +
100%: all matched users receive it - targeted rollout on +
20%: about 20% of matched users receive it - rollout at
0%: nobody receives it
Targeting Rules
A targeting rule is a pair of a property key and a list of allowed values.
For example, a rule tier → ["premium", "gold"] matches any device where the tier property is set to either "premium" or "gold".
When multiple rules are configured on a single rollout, they use OR logic. A device matches if it satisfies at least one rule. For example, with rules tier → ["premium"] and country → ["US"], a device with { tier: "premium", country: "JP" } would match because the tier rule is satisfied.
Rollout Priority
When a channel has multiple published rollouts (e.g. different bundles targeting different audiences), they are evaluated from the highest bundle version downward. The first rollout a device is eligible for wins.
This means you can layer rollouts. For example:
- Bundle v65 targeted at
tier → ["beta"]at 50% - Bundle v64 at 100% with no targeting
A non-beta user would skip v65 and receive v64. A beta user in the 50% bucket would get v65.
User Properties
User properties are key-value pairs stored on the device. The key is the property name and the value is a string describing the device's current state for that property.
Properties are sent to Bundle Drop automatically on every update check and install report. Bundle Drop uses them for two things:
- Targeting: evaluating rollout rules during OTA resolution
- Audience estimation: the dashboard's User Properties page shows how many tracked devices have reported each property key and value, so you can estimate audience size before configuring a rollout
App-Side Setup
From app code, set properties as key-value pairs whenever the relevant condition changes:
1import {
2 setUserProperty,
3 getUserProperties,
4 removeUserProperty,
5 resetUserProperties,
6} from "@gfean/react-native-bundle-drop";
7
8// Set key-value properties
9await setUserProperty("tier", "premium");
10await setUserProperty("country", "US");
11await setUserProperty("tier", "premium"); // same value, no-op
12
13const props = await getUserProperties();
14// { tier: "premium", country: "US" }
15
16// Update a value
17await setUserProperty("tier", "gold");
18// { tier: "gold", country: "US" }
19
20// Remove a property entirely
21await removeUserProperty("country");
22// { tier: "gold" }
23
24// Clear everything
25await resetUserProperties();Property keys must first be defined on the project's User Properties page in the dashboard. The keys you set in app code must match the keys configured there.
Both keys and values are case-sensitive. "tier" and "Tier" are treated as different property keys, and "premium" and "Premium" are different values. Make sure the casing in your app code matches what you configure in the dashboard.
All values must be strings. Booleans, numbers, and other types are not accepted. If you need to represent a boolean or number, pass it as a string (e.g. setUserProperty("premium", "true") or setUserProperty("level", "42")).
The relevant runtime helpers are setUserProperty(key, value) and removeUserProperty(key). Their full signatures are documented on Runtime APIs.
Dashboard-Side Setup
- Go to your project's User Properties page.
- Add the property keys your app will use (e.g.
tier,country,role). - Once devices start reporting properties, the page shows audience breakdowns per key and value — how many devices reported each value and the overall distribution.
- When configuring a staged rollout for a bundle, enable the Targeted Rollout checkbox.
- Add rules by selecting a property key and specifying the allowed values. The value dropdown is populated from values that devices have actually reported.
What the Client Needs to Know
- user properties are key-value pairs set from app code
- property keys must be defined in the dashboard before they can be targeted
- targeting rules use OR logic across rules: match any rule and the device is eligible
- targeted rollout is optional and does not replace staged rollout, it narrows it
- properties are synced to Bundle Drop automatically on every update check
Related Docs
- For gradual release control, see Staged Rollouts.
- For channel-level eligibility control, see Managed Publishing.
- For reverting a bad release, see Rollback.
- For the full function signatures, see Runtime APIs.
