Flow targeting and audience rules

When you publish a flow with auto-start conditions, Userflow evaluates those conditions for each user on every page load. If your flow isn't appearing as expected, this guide explains how targeting works and how to troubleshoot the most common causes.

If you're not sure this is a targeting problem specifically, start with the Flow not starting decision guide.

How auto-start targeting works

Userflow checks the following in order before starting a flow automatically:

1. Environment. The flow must be published in the environment the user is viewing (Production, Staging, etc.).
2. Audience conditions. Every attribute, event, and segment condition you set under Auto-start flow must be met.
3. Frequency rules. The default setting is "Only start once per user." If the user has already seen the flow, it won't start again unless you change this setting or reset the user's session.
4. Flow priority. If a user qualifies for multiple auto-start flows, the highest-priority flow displays first. After it's dismissed, the next flow in priority can appear.
5. Active flow check. Only one flow can be active for a user at a time. If the user is mid-flow on another flow (including a flow paused on a hidden step), your flow won't start.

Common reasons a flow doesn't appear

The user already saw the flow. Check the user's Sessions tab in Userflow. If the flow shows a completed or dismissed session, the frequency setting is preventing a restart. To re-trigger: delete the user's flow session from the Sessions tab, or temporarily change the frequency setting to "Multiple times per user" for testing.

The user doesn't match the audience conditions. Find the user in the Users tab and compare their attribute values against each condition in your flow. Pay attention to data types — the string "true" does not match the boolean true. The Userflow Debugger (browser extension) will also show you which specific condition is blocking the flow from starting.

The flow isn't published in the user's environment. Open the flow and check the Publish button. If it shows unsaved changes or the flow isn't enabled for Production, users in that environment won't see it.

Another flow is blocking it. Check the user's Sessions tab for any active sessions on other flows, including flows paused on a hidden step. Only one flow can be active per user at a time.

The flow is set to show only once and has already fired. This is the most common cause of "the flow worked once and never showed again." The session record is preserved even after you make edits — you need to explicitly delete the session or reset the frequency setting.

Company conditions aren't being passed. If your flow uses company-level conditions (e.g., company plan or tier), verify that your Userflow.js implementation calls userflow.group(companyId, attributes) correctly. If the company group call isn't firing, company attributes will be empty and the conditions will fail silently.

Targeting a flow to the right users (and excluding the rest)

Audience conditions do two jobs: they include the users who should see the flow and exclude everyone else. Most "the wrong people saw it" or "the right people never did" problems come down to how those conditions are combined.

• Include with attribute, event, or segment conditions. Under Auto-start flow, add the conditions a user must match — a user or company attribute (e.g. plan = pro), a tracked event (the user has done X), or membership in a Segment.
• Combine conditions with AND/OR groups. Conditions inside the same group are ANDed (all must be true); separate groups express OR logic. If the flow is reaching too few users, an unintended AND is the usual cause; if it's reaching too many, one group is broader than you think.
• Exclude users by negating a condition. To keep a flow away from a group, add a condition that is false for them — for example role is not admin, or "has not completed onboarding." There is no separate blocklist; exclusion is expressed as a negative audience condition, or by targeting a Segment that those users aren't in.
• Use Segments for reusable audiences. If you target the same population from more than one flow, define it once as a Segment and target the Segment — the rule stays consistent and you update it in a single place.
• Targeting decides who qualifies; frequency decides how often. A correctly targeted flow can still look "missing" because the user already saw it under the once-per-user default. Confirm in the user's Sessions tab before assuming the audience rule is wrong.

To confirm exactly which condition is including or excluding a specific user, open the Userflow Debugger on the page and review the condition evaluation — it shows the precise rule passing or blocking the flow for that user.

What happens when you unpublish and republish a flow

• Unpublishing stops the flow immediately for all users. Active sessions end.
• Republishing does not reset user history. Users who already completed or dismissed the flow won't see it again if the frequency is "Only start once per user."
• To re-show a flow to a user who already saw it, delete their session for that flow from the Sessions tab, or change the frequency setting.
• To reset a flow for all users, you currently need to delete sessions individually or in bulk. Contact Userflow support for bulk session reset options.

Testing your targeting conditions

Use the Userflow Debugger (Chrome extension) to see in real time which conditions are blocking your flow on a specific page and user. Open the Debugger, navigate to the page where the flow should appear, and review the condition evaluation for your flow.

→ See Using the Debugger for auto-start conditions for a full walkthrough.