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

# Study Launch Rules

> Define targeting rules that let the React Native Interviews SDK prompt eligible users to start a voice interview from app events or synced Mixpanel audiences.

Study Launch Rules connect a study to the people who should be offered it. A
rule says who becomes eligible — through a tracked app event or a synced
Mixpanel audience — and how the installed React Native Interviews SDK prompts
them. You manage rules in **Configuration → Targeting rules** on a study, and
you can change them without shipping a new app release.

## How a rule reaches a user

```text theme={null}
You create a rule (event or audience)
  -> the installed SDK loads active rules for the project
  -> a tracked event matches, or a synced audience member loads config
  -> UserJourneys checks eligibility (priority, cooldown, max starts)
  -> the SDK shows the in-app prompt
  -> the user accepts
  -> the interview opens in-app
```

The SDK evaluates a tracked event locally first and ignores events that no rule
targets. Eligibility, priority, cooldown, and start limits are enforced on the
server, so changing a rule takes effect for installed apps without an update.

## Trigger types

Every rule has one trigger, fixed when the rule is created.

<CardGroup cols={2}>
  <Card title="App event" icon="bolt">
    Fires when a user triggers a named event in your mobile app, such as
    `Order Completed`. The SDK matches the event name and asks UserJourneys
    to resolve a launch.
  </Card>

  <Card title="Synced audience" icon="users">
    Makes everyone in a synced Mixpanel cohort eligible. When a user's
    `referenceId` matches an active audience member, the SDK receives a pending
    prompt while loading config.
  </Card>
</CardGroup>

## Set up targeting rules

<Steps>
  <Step title="Get your Interviews SDK key">
    In the dashboard, go to **Settings → API keys** and copy the
    **Interviews SDK key**. This public key is the only credential the mobile SDK
    needs.
  </Step>

  <Step title="Install the React Native SDK">
    Add the SDK to your app and create the client with that key. See the
    [React Native quickstart](/react-native-interviews/quickstart).
  </Step>

  <Step title="Provide a trigger source">
    For an app-event rule, make sure your app tracks the event through the wrapped
    analytics client. For an audience rule, sync the Mixpanel cohort first — see
    [Mixpanel cohort sync](/funnels/mixpanel).
  </Step>

  <Step title="Create the rule">
    Open the study, go to **Configuration → Targeting rules**, and click
    **Add rule**. Choose the trigger, pick the event or audience, write the prompt
    copy, set pacing limits, and set the status to **Active**. The tab appears
    once your app has contacted the SDK API — run the app once after installing
    the SDK.

    <Note>
      The event picker suggests events UserJourneys has already observed for your
      project. You can also type an event name the catalog has not seen yet.
    </Note>
  </Step>

  <Step title="Confirm the SDK is connected">
    Once an app has contacted the project's SDK API with your key, the
    **SDK not connected yet** warning disappears and active rules can fire.
  </Step>
</Steps>

## What the user sees

For an `SDK prompt` rule, the SDK shows an in-app card with your prompt heading,
message, an accept button, and a dismiss button. Accepting opens the interview
in-app; dismissing clears the prompt without opening anything. Empty copy
fields fall back to the SDK defaults.

A `Direct link` rule makes the study available without showing this prompt
card.

## Field reference

<ResponseField name="Rule name" type="string">
  An internal label to find the rule later. Users never see it.
</ResponseField>

<ResponseField name="Status" type="active | draft | paused">
  **Active** runs the rule now, **Draft** saves it without launching, and
  **Paused** turns it off temporarily. Archiving removes a rule from the study.
</ResponseField>

<ResponseField name="How it's offered (surface)" type="SDK prompt | Direct link">
  **SDK prompt** shows an in-app card the user can accept. **Direct link** makes
  the study available without a prompt.
</ResponseField>

<ResponseField name="Priority" type="integer">
  When several rules match the same person at the same time, the rule with the
  **higher number wins**. Default 100; range 0–10000.
</ResponseField>

<ResponseField name="Cooldown between prompts" type="seconds">
  The minimum time before the same person can be prompted again. 0 means no wait;
  maximum 30 days, in seconds.
</ResponseField>

<ResponseField name="Max starts per person" type="integer">
  How many times one person can start this study from this rule. Default 1; range
  1–100.
</ResponseField>

<ResponseField name="Prompt copy" type="object">
  The text on the in-app prompt card for `SDK prompt` rules: a prompt heading
  (up to 120 characters), a prompt message (up to 500 characters), an accept
  button label, and a dismiss button label. Any field left blank uses the SDK
  default.
</ResponseField>

<ResponseField name="Extra metadata" type="object">
  Optional advanced mapping of metadata keys to respondent fields (for example
  `traits.plan`) to attach to each interview. Leave it empty unless you need it.
</ResponseField>

## When several rules match

Rules are evaluated highest priority first. For an app event, the highest
priority rule that targets that event name is used. For a synced audience,
audiences are evaluated highest priority first. After a rule is selected, its
cooldown and max-starts limits decide whether the person is prompted; if the
limit is reached or the cooldown is active, the launch is not eligible.

## Before the SDK is installed

Rules are delivered through the Interviews SDK. A rule can only reach someone
after an app has contacted the project's SDK API with your Interviews SDK key.

The **Targeting rules** tab appears in study configuration once your app has
connected, or once the project already has launch rules. Before that, start
from **Settings → API keys** to get the Interviews SDK key and install the SDK.
If rules exist while the SDK is not connected, the tab shows an
**SDK not connected yet** warning.

<Note>
  Rules created before the SDK is installed (for example through the chat agent)
  are stored and ready, but they will not fire until the SDK is connected.
</Note>

## Why isn't anyone getting prompted?

If a rule is live but no one is seeing the prompt, work through this checklist
from the most common cause down:

* **The study is not activated.** A rule on a study that is not active never
  prompts anyone. Activate the study first.
* **The rule is paused, a draft, or archived.** Only `Active` rules fire. Check
  the rule's status.
* **The event name does not match.** App-event rules match the tracked event
  name exactly, including spaces and capitalization. `Order Completed` does not
  match `order_completed`.
* **The person hit the max starts or is in cooldown.** Once a person reaches the
  rule's max starts per person, or while the cooldown is active, they are not
  eligible again. See [Testing your rules](#testing-your-rules) to test with a
  fresh person.
* **The person dismissed a recent prompt.** A recently dismissed prompt does not
  immediately reappear.
* **The person is not in the synced audience.** For audience rules, the person's
  `referenceId` must match an active member of the synced cohort. Confirm the
  cohort sync ran and includes that person.
* **The SDK is not installed or connected.** Rules are delivered through the
  Interviews SDK. If the **SDK not connected yet** warning is showing, no app has
  contacted the project's SDK API with your key — install the SDK and run the app
  once.

## Testing your rules

Limits, cooldowns, and dismissals are keyed off the `referenceId`, so once a test
person has hit a limit or a cooldown, that same id will not prompt again. To
re-run a rule cleanly, use a fresh throwaway `referenceId` for each test run —
for example `dev-test-1`, then `dev-test-2` — so the new id has no start history,
cooldown, or dismissal. Switch back to your real `referenceId` before you
release.

<Note>
  An invite link is a plumbing test that bypasses launch rules: it opens the
  interview directly without checking event match, audience membership, priority,
  cooldown, or max starts. Use an invite link to confirm the interview itself
  works, and use a fresh `referenceId` to confirm the rule's targeting and
  eligibility.
</Note>

For the full in-app validation checklist (event wrapping, WebView, microphone,
fallback, attribution), see
[Test your integration](/react-native-interviews/testing).

## Managing rules with the chat agent

The chat agent can list, create, update, and archive Study Launch Rules for you.
When it manages rules it also reports whether the SDK is connected, so it can
warn you when a rule cannot reach anyone yet because the SDK is not installed.

## Related

<CardGroup cols={2}>
  <Card title="React Native quickstart" icon="mobile" href="/react-native-interviews/quickstart">
    Install the SDK and create the client with your Interviews SDK key.
  </Card>

  <Card title="Mixpanel cohort sync" icon="link" href="/funnels/mixpanel">
    Sync Mixpanel cohorts so they appear as audiences for audience rules.
  </Card>
</CardGroup>