> For the complete documentation index, see [llms.txt](https://docs.userlane.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.userlane.com/best-practices/audiences-design-test-and-keep-them-accurate.md).

# Audiences: design, test, and keep them accurate

How to design audiences that target the right end users and stay accurate over time.

An audience[^1] is a reusable group of end users defined by attribute conditions. Its main job is targeting: it controls which end users see which content. Audiences work best for groups that stay relevant over time, such as departments, roles, or locations. The same audiences are also available as analytics filters, which is useful when you need a long-lived view of one group. For one-off analysis, filtering by attributes directly is usually faster than creating an audience.

## How it works

{% stepper %}
{% step %}

#### Decide what groups matter

Start from the groups the organization manages differently, not from whatever data happens to be available.

Three questions help identify the right groups:

1. **Do different groups complete different processes?** A hospital where nurses and pharmacists use the same electronic patient record (EPR) system but run different workflows needs separate audiences for each role. A software company where all users follow the same onboarding path may need only new-versus-returning.
2. **Does the organization report adoption to different managers on a regular basis?** If HEART results need to be reported by department or site over time, an audience for each group makes that reporting repeatable.
3. **Are there groups that should not see certain content?** Contractors, read-only users, and administrators often need to be excluded from onboarding guides or feature announcements. Advanced users who already know the application may not need onboarding content at all.
   {% endstep %}

{% step %}

#### Choose the right attribute source

Audiences are built from attributes[^2]. There are three ways to get attribute data into Userlane, and the choice determines whether audience definitions stay current or go stale.

<table><thead><tr><th width="139.083251953125">Source</th><th>What it does</th><th>Best for</th></tr></thead><tbody><tr><td><a href="/administration/attributes/attributes-from-sso.md">Single sign-on (SSO)</a></td><td>Passes attributes at login from the identity provider. Available immediately, but limited to what the directory holds.</td><td>Basic attributes the identity provider maintains: email domain, authentication group</td></tr><tr><td><a href="/administration/attributes/connect-an-attribute-source.md">Connectors</a></td><td>Userlane connects to a system of record (a human resources (HR) system, a customer relationship management (CRM) system, or an identity provider) and pulls attributes on a daily schedule.</td><td>Department, job title, location, employment status: fields the organization already maintains elsewhere</td></tr><tr><td><a href="/developer-reference/push-user-attributes-via-api.md">Attribute Import API</a></td><td>Your team sends attribute data to Userlane through the application programming interface (API) on your own schedule.</td><td>Custom attributes from systems not in the connector catalog, or from internal data pipelines</td></tr></tbody></table>

Connectors are the most reliable option for organizational attributes because the system of record owns the data and updates flow automatically. SSO depends on optional directory fields that are often incomplete. The API suits teams with engineering capacity and non-standard sources. [Attribute sources](/administration/attributes/attribute-sources.md) compares every option in detail.

{% hint style="info" %}
**Check attribute coverage before building audiences.** A connector that maps "department" does not guarantee that every user has a department value. Connecting a source does not improve the data inside it. If department is populated for half the users, an audience based on department will miss the other half, silently.
{% endhint %}
{% endstep %}

{% step %}

#### Build conditions that stay accurate

When you [create an audience](/administration/audiences/build-an-audience-from-attribute-rules.md) in the portal, combine attribute conditions with AND/OR logic.

**Get the conditions right once.** An audience is one definition, applied everywhere it is used. A condition that is too broad or too narrow shows content to the wrong people, and if the audience is also used as an analytics filter, it skews those numbers too. For example, `Department = Finance` excludes "Finance Operations," while `Department contains Finance` includes it. Decide which one you mean before publishing content to the audience.

<table><thead><tr><th width="157.447021484375">Condition type</th><th>Example</th><th>When to use</th></tr></thead><tbody><tr><td>Attribute equals</td><td>Department = "Finance"</td><td>Exact group match from a system of record</td></tr><tr><td>Attribute contains</td><td>Job title contains "Manager"</td><td>Partial match when titles vary across regions</td></tr><tr><td>Behavioral</td><td>Completed Guide X = false</td><td>Target users who have not finished onboarding</td></tr><tr><td>Activity-based</td><td>Last active more than 30 days ago</td><td>Re-engage inactive users</td></tr></tbody></table>

**Conditions to avoid:**

* **Hard-coded user IDs.** These do not scale and break when users leave.
* **Attributes with low coverage.** If "department" is populated for 40% of users, an audience based on department misses 60%. Check attribute coverage in the portal before relying on a field.
* **Overlapping audiences with no clear precedence.** If a user matches both "New users" and "Finance," and both carry different content, the user sees both. Design audiences so overlap is intentional or impossible.

<div data-with-frame="true"><figure><img src="https://259567114-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FF6bxg8i3T6U4vZ3k7PHi%2Fuploads%2F5AxC6ASYKwSu41jifr9w%2FAudience%20Analytics.png?alt=media&#x26;token=42b1706a-1f81-4d27-8f67-55f620e237d3" alt="Audience Analytics in the Userlane portal, showing metrics filtered by audience"><figcaption><p>When an audience also filters analytics, a condition error skews the numbers as well as the content.</p></figcaption></figure></div>
{% endstep %}

{% step %}

#### Apply audiences at the right level

Audiences can be set at two levels:

* **Chapter level.** All guides in a chapter inherit the chapter's audience. Use this for broad targeting: all finance guides visible only to finance users.
* **Individual content level.** A single guide, tooltip, or announcement can have its own audience on top of the chapter audience. The conditions stack: the user must match both.

Audiences can also be selected as filters in analytics, to see HEART, guide completion rates, and other metrics for that group.
{% endstep %}

{% step %}

#### Test before activating

Audience mistakes are one of the most common reasons teams contact support. Most problems come from the same patterns:

* **Case sensitivity.** "Finance" and "finance" are different values. If the source system sends lowercase and the audience condition expects title case, the audience matches nobody. Check the exact casing the source sends.
* **Attributes not being sent.** An audience condition that references an attribute nobody set up in the Userlane implementation will return zero users, silently. Confirm with the team responsible for the implementation that every attribute used in an audience definition is actually being sent.
* **Admin testing trap.** When you log in as yourself in the portal, the browser extension evaluates audience rules against your own profile, not the end user you want to test for. Use preview mode in the [Editor](/assistance/a-tour-of-the-editor.md) or create a test account with the correct attributes.
* **Scope mismatch.** Attributes from connectors apply to all applications. Attributes passed through the Userlane implementation on a specific application apply only to that application. Mixing the two in one audience can produce unexpected results.

When rolling out a new audience, test it on a small group first. Confirm the audience matches the expected users and that the right content appears before you apply it to the full user base.
{% endstep %}
{% endstepper %}

## How to know it is working

At each quarterly review, check three things:

1. **Audience coverage.** What percentage of active users match at least one audience? If coverage is low, either attributes are not being sent for all users (check the attribute source in the portal) or the audience conditions are too narrow.
2. **Targeting accuracy.** Do guides targeted at a specific audience show higher completion rates than untargeted equivalents? If not, the audience definition may not match the group that actually needs the guide.
3. **Attribute freshness.** When did the attribute source last sync? Stale data means audience membership may not reflect recent changes: new hires, department transfers, role changes.

{% hint style="warning" %}
**Caveat.** An audience with zero matched users is not necessarily an error. It may mean the attribute is not being sent, the condition has a casing mismatch, or the connector has not synced yet. Check the attribute source before adjusting the condition.
{% endhint %}

## Relevant articles

{% content-ref url="/pages/TKBRGmMaapWk0xuF3XwG" %}
[Audiences](/administration/audiences.md)
{% endcontent-ref %}

{% content-ref url="/pages/Zk1PSRimln0YLI1l2ZkI" %}
[Build an audience from attribute rules](/administration/audiences/build-an-audience-from-attribute-rules.md)
{% endcontent-ref %}

{% content-ref url="/pages/gtcOzAVjL7zzv75As2Jd" %}
[Attributes](/administration/attributes.md)
{% endcontent-ref %}

{% content-ref url="/pages/heUmxS6HxlGKqCQSjqbs" %}
[Attribute sources](/administration/attributes/attribute-sources.md)
{% endcontent-ref %}

{% content-ref url="/pages/xrl3g8ZSEVCM0qRA7ZCH" %}
[Content planning: how to structure a content set that scales](/best-practices/content-planning-how-to-structure-a-content-set-that-scales.md)
{% endcontent-ref %}

## FAQ

<details>

<summary>How many audiences should an application have?</summary>

Start with the groups the organization already manages differently: departments, roles, experience levels. Add behavioral audiences (new users, inactive users) once the first content set is live and analytics show where targeting gaps exist. More audiences are not better; more accurate audiences are.

</details>

<details>

<summary>Can an audience be reused in multiple applications?</summary>

Audiences based on attributes from connectors or the API (at company scope) apply to all applications. Audiences based on attributes passed through the implementation on a specific application are limited to that application, because different applications may send different values for the same user.

</details>

<details>

<summary>What happens when a user matches multiple audiences with different content?</summary>

The user sees all content from all matched audiences. Userlane does not enforce mutual exclusivity. If this is not the intended behavior, redesign the audience conditions so a user matches only one. Alternatively, accept the overlap and make sure the content still makes sense when combined.

</details>

<details>

<summary>How often do connector-sourced attributes refresh?</summary>

Connectors sync once every 24 hours. The first sync after connecting a source lands within approximately 15 minutes. There is no on-demand sync option. The API supports any cadence the organization chooses.

</details>

<details>

<summary>What is the difference between an audience and a display rule?</summary>

An audience targets people (who sees the content). A display rule[^3] targets pages (where the content appears). Both can be applied to the same content item independently. A guide can be visible only to finance users (audience) and only on the invoicing page (display rule).

</details>

[^1]: An audience is a group of users defined by attribute rules, used to decide who sees Userlane content.

[^2]: An attribute is a fact about a user, such as department, job title, location, or employment status.

[^3]: A display rule is a URL-based condition that controls which pages content appears on.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.userlane.com/best-practices/audiences-design-test-and-keep-them-accurate.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.