> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trypillow.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Target SDK audiences

> Automatically launch studies to specific cohorts of your SDK users

Audience targeting lets you push studies to specific groups of users who have the Pillow SDK installed. Instead of sharing a link or manually triggering `presentStudy()`, you define a cohort and Pillow automatically presents the study when matching users open your app.

## How it works

1. You describe a cohort using a set of **targeting rules**: activity rules and property filters.
2. You set a **cooldown** and an **engaged interviews goal**.
3. Pillow locks in the audience of every user that matches at launch time.
4. As users open your app, the SDK checks for a pending study and presents it.
5. The run ends when the goal is reached, every eligible user has been presented, or you stop it manually.

<Note>
  Audience targeting only applies to users reached through the Pillow SDK. Users who open your study from a shared link or the embeddable website widget are not affected.
</Note>

## Prerequisites

Before you can launch an audience, you need:

* A **live alias** on the study (promote the study to live from the Overview tab)
* An **app** registered in **Developer** with at least one API key (see [Apps and API keys](/sdk/apps-and-keys))
* The **Pillow SDK** integrated in that app (see the [Web](/sdk/web/getting-started), [iOS](/sdk/ios/getting-started), or [Android](/sdk/android/getting-started) guides)
* **User identification** via `setExternalId()` and, for property-based targeting, `setUserProperty()` (see [Identification](/sdk/web/identification))

## Create an audience

<Steps>
  <Step title="Open the Integration tab">
    Go to your study's **Settings** and open the **Integration** tab. Scroll to **SDK distribution → Target audience**.
  </Step>

  <Step title="Click Create audience">
    Click **Create audience**. If a previous run already exists, this button is labeled **New audience**.
  </Step>

  <Step title="Pick the app">
    Choose which app to target. All platforms (Web, iOS, Android) that share this app's API key are included. Deactivated apps cannot be selected.
  </Step>

  <Step title="Add targeting rules">
    Build your cohort using activity rules and property filters (see [Targeting rules](#targeting-rules) below). The audience size at the bottom of the drawer updates automatically as you edit the rules.
  </Step>

  <Step title="Set the cooldown and goal">
    Set the **Cooldown period** (days to wait before the same user can be presented again) and the **Engaged interviews goal** (the run stops automatically when this many interviews are completed).
  </Step>

  <Step title="Launch">
    Click **Launch**. Pillow locks in the matching users and starts presenting the study on their next app open.
  </Step>
</Steps>

<Tip>
  If a run is already active for this study, launching a new one prompts you to confirm. The active run is stopped and replaced by the new one.
</Tip>

## Targeting rules

All rules are combined with **AND**, so only users matching every rule are included in the audience.

### Activity

Two sentence-style rules describe how recently a user has interacted with your app. Leave either blank to skip that rule.

* **User has been active in the last N days**: filters users whose most recent session is within the window.
* **User has installed the app in the last N days**: filters users whose first session is within the window.

### Property filters

Click **Add property filter** to target users by a property. Each filter reads as a sentence: *"has property **X** **is** **Y**"*.

**Properties** you can filter on:

| Property            | Source                                            |
| ------------------- | ------------------------------------------------- |
| Platform            | Auto-detected (`iOS`, `Android`, or `Web`)        |
| Locale              | Auto-detected (e.g. `en-US`, `fr-FR`)             |
| App version         | Auto-detected from your app build                 |
| Country             | Auto-enriched from IP address                     |
| Region              | Auto-enriched from IP address                     |
| City                | Auto-enriched from IP address                     |
| Any custom property | Values you set via `setUserProperty()` in the SDK |

<Note>
  Custom properties only appear in the dropdown once your SDK has reported them for at least one user. If a property is missing, confirm the SDK is calling `setUserProperty()` in that app.
</Note>

**Operators:**

| Operator                                                         | Applies to                                 | Behavior                                         |
| ---------------------------------------------------------------- | ------------------------------------------ | ------------------------------------------------ |
| `is`                                                             | All properties                             | Exact match against a single value               |
| `is any of`                                                      | All properties                             | Match against any value in a list (multi-select) |
| `is not`                                                         | Custom properties only                     | Excludes rows with the given value               |
| `greater than`, `less than`, `greater or equal`, `less or equal` | Custom properties with numeric values only | Numeric comparisons                              |

Built-in properties (Platform, Locale, App version, Country, Region, City) only support `is` and `is any of`.

**Values:** the value picker is a searchable dropdown backed by the values your SDK has actually reported. Start typing to filter the list, or press **Enter** to use a custom value you typed in.

## Audience size

The drawer shows the live estimate at the bottom:

* **Audience size**: how many users currently match all rules (after cooldown).
* **Will stop when reaching**: the engaged interviews goal.

The estimate recomputes automatically as you change rules. If the audience is empty, Pillow shows a warning and disables **Launch**.

<Tip>
  When you narrow the filters so that the audience drops below your engaged goal, Pillow automatically lowers the goal to match. It never asks for more interviews than there are eligible users.
</Tip>

## Runs

Each launch creates a **run**. The active run (if any) sits at the top of **Target audience**, followed by up to five past runs. Click **Details** to expand the full rule breakdown.

Each run card shows three metrics:

| Metric        | What it means                                                   |
| ------------- | --------------------------------------------------------------- |
| **Audience**  | Users locked in at launch time                                  |
| **Presented** | Users who have been shown the study so far                      |
| **Engaged**   | Users who completed an interview, with progress toward the goal |

### Status

| Status        | Description                                                             |
| ------------- | ----------------------------------------------------------------------- |
| **Building**  | Pillow is still computing the audience                                  |
| **Running**   | The study is being presented to users as they open the app              |
| **Completed** | The engaged goal was reached, or every eligible user has been presented |
| **Stopped**   | You stopped the run manually                                            |
| **Failed**    | The audience could not be built. Contact support                        |

You can rename any run by clicking its title. Rename runs to keep track of experiments (e.g. *"Power users (FR)"*, *"Free tier, onboarding"*).

### Audience at launch

The audience is a fixed list of users who matched your rules at launch. New users that start matching later are **not** added to the current run. Launch a new audience if you want to reach them.

### Cooldown

The cooldown excludes any user who has already been presented with **any Pillow study** in the last N days. Use it to avoid fatiguing the same users across multiple studies.

### Stopping a run

Click **Stop** on the active run to end it immediately. Users still in the audience won't be presented anymore, but interviews already in progress continue.

## SDK integration

Audience targeting requires one extra hook beyond the standard SDK setup so your app knows when it's safe to present a study.

### Web

The browser SDK checks for a pending launch study during its audience heartbeat. No extra code is needed beyond the standard initialization. To force a check (for example after a key user action), call:

```ts theme={"theme":{"light":"github-light","dark":"github-dark"}}
await sdk.presentLaunchStudyIfAvailable();
```

See [Web SDK: Launch studies](/sdk/web/studies#launch-studies).

### iOS

Call `onReadyToPresentStudy()` from the view controller that should host the study (typically after your main UI is loaded).

```swift theme={"theme":{"light":"github-light","dark":"github-dark"}}
PillowSDK.shared.onReadyToPresentStudy()
```

See [iOS SDK: Launch studies](/sdk/ios/studies#launch-studies).

### Android

Call `onReadyToPresentStudy()` from your Activity's `onResume()`.

```kotlin theme={"theme":{"light":"github-light","dark":"github-dark"}}
override fun onResume() {
    super.onResume()
    PillowSDK.onReadyToPresentStudy(activity = this)
}
```

See [Android SDK: Launch studies](/sdk/android/studies#launch-studies).

## What's next

<CardGroup cols={2}>
  <Card title="Apps and API keys" icon="key" href="/sdk/apps-and-keys">
    Register an app and generate an API key.
  </Card>

  <Card title="Identification" icon="user" href="/sdk/web/identification">
    Identify users and set properties used for targeting.
  </Card>

  <Card title="Web SDK studies" icon="globe" href="/sdk/web/studies">
    Present studies and handle launch studies on the web.
  </Card>

  <Card title="Broadcast your study" icon="share" href="/guides/broadcast-study">
    Other ways to distribute your study.
  </Card>
</CardGroup>