# Targeted Rollout — Bundle Drop Docs

> Target Bundle Drop OTA releases to specific users by plan, country, or role using user property rules.

Canonical: https://bundledrop.app/docs/targeted-rollout-properties

## 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](/docs/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](/docs/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.

In this read-only example, `plan = pro` filters the audience first, then a stable bucket decides eligibility at 10%, 25%, 50%, and 100%. Even at 100%, free-plan installs remain outside the audience. Devices discover availability on their next update check; activation follows the app's update policy.

## How It Works

At a high level:

1. In the dashboard, you define the user properties your project uses on the project's **User Properties** page (e.g. `tier`, `country`, `isBetaUser`, `accountAge`).
2. In your app, you set key-value pairs for those properties based on your product logic (e.g. `tier = "premium"`, `country = "US"`, `isBetaUser = true`).
3. When configuring a rollout, you enable targeted rollout and add one or more targeting rules. Each rule specifies a property and one or more target values.
4. When a device checks for updates, Bundle Drop evaluates the rules against the device's current properties. If **any** rule matches, the device passes the audience filter.
5. After that, the rollout percentage is applied to the matched group.

Examples:

- targeted rollout on + `100%`: all matched installs are eligible
- targeted rollout on + `20%`: about 20% of matched installs are eligible
- rollout at `0%`: no installs are eligible

Eligibility is evaluated on an update check. Downloading and activating the bundle follow the app's configured [update policy](/docs/update-policies).

The percentage is applied using each install's stable bucket, so the matched 20% stays the same set of devices as you ramp the percentage up — see [How Devices Are Chosen](/docs/staged-rollouts).

## Targeting Rules

A targeting rule is a pair of a property key and a list of target values.

For example, a rule `tier → ["premium", "gold"]` matches any device where the `tier` property is set to either `"premium"` or `"gold"`.

Values are typed by the property definition. A string property targets text values such as `"premium"` or `"US"`, a number property targets numeric values such as `33`, and a boolean property targets `true` or `false`.

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 describes the device's current state for that property. Values can be strings, finite numbers, or booleans.

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 update checks
- **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:

**targeted-rollout.ts**

```ts
import {
  setUserProperty,
  getUserProperties,
  removeUserProperty,
  resetUserProperties,
} from "@gfean/react-native-bundle-drop";

// Set key-value properties
await setUserProperty("tier", "premium");
await setUserProperty("country", "US");
await setUserProperty("accountAge", 33);
await setUserProperty("isBetaUser", true);
await setUserProperty("tier", "premium"); // same value, no-op

const props = await getUserProperties();
// { tier: "premium", country: "US", accountAge: 33, isBetaUser: true }

// Update a value
await setUserProperty("tier", "gold");
// { tier: "gold", country: "US", accountAge: 33, isBetaUser: true }

// Remove a property entirely
await removeUserProperty("country");
// { tier: "gold", accountAge: 33, isBetaUser: true }

// Clear everything
await 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.

Property keys and string 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.

Values must match the property's type. String properties accept strings, number properties accept finite numbers, and boolean properties accept `true` or `false`.

The relevant runtime helpers are `setUserProperty(key, value)` and `removeUserProperty(key)`. Their full signatures are documented on [Runtime APIs](/docs/runtime-apis).

## Dashboard-Side Setup

1. Go to your project's **User Properties** page.
2. Add the property definitions your app will use, including the key and value type (e.g. `tier` as a string, `isBetaUser` as a boolean, `accountAge` as a number).
3. Once devices start reporting properties, the page shows audience breakdowns per key and value — how many devices reported each value and the overall distribution.
4. When configuring a staged rollout for a bundle, enable the **Targeted Rollout** checkbox.
5. Add rules by selecting a property key and specifying the target values. The dashboard can suggest values devices have reported, and you can enter a new value when needed.

## What the Client Needs to Know

- user properties are key-value pairs set from app code
- property definitions must be created in the dashboard before they can be targeted
- values can be strings, finite numbers, or booleans
- 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](/docs/staged-rollouts).
- For channel-level eligibility control, see [Managed Publishing](/docs/managed-publishing).
- For reverting a bad release, see [Rollback](/docs/rollback).
- For the full function signatures, see [Runtime APIs](/docs/runtime-apis).