Setup and Targeting

Targeting controls which users receive your guide or survey. Triggering controls when and where it appears. Both settings live in the Setup tab in the builder.

Targeting

Not every message is for every user. Targeting lets you define which users receive your guide or survey, and when. You can target either All Users or Targeted Users.

All Users targets every user who visits your site with this guide or survey.

Targeted Users lets you create segments of users to receive your guide or survey.

Each segment can filter by property or cohort, and can have multiple filters. For example, target your guide or survey to users from outside the United States who are new users within the last 30 days.

The property picker includes transformed user properties defined in Amplitude Data alongside standard user properties. Targeting on transformed properties ensures the users your guide or survey reaches match the same population you see in Analytics charts and cohorts, because both use the same transformation rules.

Array user properties

Guides and Surveys evaluates targeting rules during remote evaluation. The user property store that powers this evaluation flattens nested objects, but it doesn't flatten array-valued properties.

If you send a property as an array of objects (for example, subscription: [{plan, state, length}]), dotted paths like subscription.plan aren't available at evaluation time, even if those paths appear on user profiles in Analytics. Cart Analysis creates those dotted properties for Analytics, but they don't sync to the user property store that Guides and Surveys reads.

To target on array-derived values, set a flat scalar user property (for example, subscription_plan: "enterprise") and target that property instead.

You can set both rollout percentage and bucketing unit for your user segments. For example, target 10% of a segment when you first publish a guide, then increase it to 100% after you confirm the engagement data.

Using more than one segment

When you add more than one segment to your targeting, Amplitude ORs each segment. This means that if a user belongs to any segment, Amplitude shows them the guide or survey.

Distribute eligibility evenly

Even distribution spreads a web guide or survey across a recurring period instead of immediately making the entire targeted audience eligible. Use it when you need a steady stream of impressions or responses, such as an ongoing NPS program, rather than a spike when you publish.

Each user gets one consistent 14-day eligibility window during every recurrence period. Amplitude distributes the window start dates across the period and uses the same User ID to keep a user's assignment stable across sessions and devices. For anonymous visitors, Amplitude uses the Device ID, so the same person can have a different window on each device.

The recurrence period controls how often each user's window repeats. It doesn't change the 14-day window length. For example, with a 90-day period, a user can become eligible during their assigned 14 days in each 90-day cycle. If you change the period, Amplitude recalculates the assigned start date, which can change when a user next becomes eligible.

Even distribution adds another targeting check. A guide or survey appears only when the user is inside their window and also passes the audience, page targeting, trigger, status, and limit checks. Even distribution doesn't guarantee an impression or response. If the user doesn't visit or meet the trigger during their window, they must wait for their window in the next cycle.

Configure even distribution

Open a web guide or survey and go to the Setup tab.
In the Targeting section, turn on Even distribution.
Under Distribute across, select Every 30 days, Every 60 days, Every 90 days, Every 180 days, or Every 365 days. Amplitude selects 90 days by default.
Save the guide or survey.

During testing, open the Targeting status in the debug toolbar to check whether the current user is inside their 14-day window.

Use cases

Recurring NPS surveys: Spread a quarterly NPS program across 90 days to collect a steadier flow of responses throughout the quarter.
Continuous product feedback: Distribute a recurring satisfaction or feature-feedback survey so responses represent different points in the period.
Staged guide delivery: Roll out an evergreen education guide gradually to reduce a launch-day spike in impressions or downstream activity.

Limits and availability

Even distribution works with limits rather than replacing them. A user who has completed or dismissed an experience remains ineligible in later windows when either the Stop showing when completed or the Stop showing when dismissed limitations apply. Review those settings and configure a Cooldown limit if you want users to receive a recurring survey while limiting how often it appears. A survey response cap remains cumulative and can still unpublish the survey.

You can use even distribution for web guides and surveys, except tooltips, when your plan includes recurrence. Mobile guides and surveys don't support it.

User targeting best practices

Property	When to use	Notes
First Seen	Target new users instead of using a cohort. Cohort membership updates with a delay, so a cohort-based new-user filter misses users on their first visit. Add a filter where First Seen is greater than or equal to today's date to reach users who signed up that day. If a user doesn't visit a page where the guide appears on their first login, they remain eligible on future logins because their First Seen timestamp doesn't change.	Guides and Surveys pulls this timestamp from the Amplitude ID table during remote evaluation, so it's available even on a user's very first session.
[Amplitude] Device Category Web only	Target web users by device type instead of `[Amplitude] Device type` or `Device family`, which expose hundreds of values. Accepts `desktop`, `mobile`, or `tablet` with `is` or `is not`. For example, add `[Amplitude] Device Category is not mobile` to keep a guide off mobile browsers.	The browser SDK detects device category from the user agent on each request. It isn't a stored user property, so Guides and Surveys evaluates it when the user arrives with no cohort sync delay. Doesn't appear for iOS, Android, React Native, or Flutter.

Bucketing units

The bucketing unit determines how Amplitude assigns users to receive your guide or survey when you use rollout percentages. Bucketing keeps the experience consistent across devices and sessions for the same entity.

Available bucketing units

Bucketing unit	Behavior
User ID	Buckets users by user ID. When a user logs in from different devices, they remain in the same bucket and receive a consistent experience. This is the default.
Device ID	Buckets users by device identifier. Each device receives an independent assignment, so the same user on different devices might have different experiences.
Account ID or Organization ID	Buckets users by a custom property like account ID or organization ID. Use this when all users in the same organization need the same experience. For example, if you test a feature with 50% of accounts, all users in a selected account see the feature, and all users in excluded accounts don't.

Bucketing examples

Example 1: User ID bucketing

You set a 50% rollout with User ID bucketing. A user logs in on a laptop and receives the guide. After the user later logs in on a phone with the same user ID, the user continues to see the guide because Amplitude bases bucketing on user ID.

Example 2: Account ID bucketing

You set a 50% rollout with Account ID bucketing (using a custom account_id property). Account "Acme Corp" with 10 users falls into the selected 50%. All 10 users from Acme Corp see the guide, regardless of device. All users from "Beta Inc" in the other 50% don't see the guide.

Example 3: Device ID bucketing

You set a 50% rollout with Device ID bucketing. A user's laptop falls into the selected 50% and receives the guide. The same user's phone falls into the other 50%, so the guide doesn't appear on the phone, even though both devices belong to the same user.

When to use each bucketing unit

User ID: Use when you want consistent experiences for logged-in users across their devices.
Device ID: Use for anonymous users or when device-specific targeting matters.
Account/Organization ID: Use when all users in an organization need the same experience. This is useful for B2B products or organizational rollouts.

Estimated reach

As you configure targeting, the builder shows an estimated number of sessions that match. The estimate accounts for the guide's platform, any custom throttles, and any project-wide exclusions, so tightening a throttle or excluding a cohort lowers the estimate even when targeting stays the same.

Two things to keep in mind:

Session-based, not user-based. One user across several sessions counts more than once.
Historical, not guaranteed. The estimate comes from historical session data. Page targeting and trigger conditions evaluate in the browser at display time, so they aren't included in the estimate.

Exclude a group of users

You may want to exclude a group of users from a specific guide or survey. For example, you might run a survey but exclude customers in the United States, or exclude internal users to receive responses only from actual customers.

You can exclude users at the cohort or segment level. The process is similar for both. This section focuses on excluding at the cohort level. Refer to Cohorts for more information about cohorts.

To exclude a cohort of users, set the where statement to does not equal the cohort you want to exclude.

Project-wide default user exclusions

Set default user exclusions at the project level to hide every guide and survey from a group of users, such as internal employees or demo accounts. Amplitude applies the exclusion to all existing and future guides and surveys in the project, including experiences that are already running, so you don't need to repeat the same exclusion on each one.

To configure default user exclusions:

In Guides and Surveys, open the guides or surveys list and click the Settings icon.
Expand Default user exclusions.
Under Exclude users where, add one or more segments. Build each segment from user property conditions, including cohort membership.
Click Save.

A user who matches any of these segments never sees a guide or survey in the project. Individual experiences can add their own exclusions on top of the project-wide defaults, but they can't override or replace them.

Default user exclusions require the same permission as throttling and default page exclusions. The exposure estimate in the builder subtracts users who match a project-wide exclusion.

Send a link to a guide

Send users a link to your guide or survey to target them more directly. From the guide or survey builder, expand the menu next to the Save button, and select Share link.

In the modal:

For web, copy the query parameter and append it to a page on your site that's instrumented with Guides and Surveys. When the recipient selects the link with the query parameter attached, the guide displays.
For mobile, scan the QR code or open the share link URL on a device with your app installed. The guide displays in the app.

User and page targeting

When you send a direct link to a guide or survey, Amplitude overrides any audience or user targeting you set on the guide.

Amplitude doesn't override page targeting. To ensure the link works as expected, confirm the page you send can display the guide.

Triggers

Triggers control when and where the experience appears.

Within the targeting card, select what events or interactions launch the experience, gate the experience to specific pages, and adjust the priority.

When

Amplitude provides the following options to trigger an experience.

Trigger	Description
None	The experience doesn't appear by default. Select this option to launch the experience through the SDK, through a call to action (CTA) in another guide or survey, or through any other external trigger.
Immediately	The experience appears after the page loads.
When element appears	Launches the experience when a specified element appears on screen. Enter a CSS Selector or XPath path expression, or select Test and Preview to launch the visual selector. This trigger fires once per page load. Amplitude can't detect whether the element has reappeared or is still present, so the experience doesn't re-trigger if the element scrolls out of view and back in. This scroll caveat applies to the trigger only and doesn't affect how pin steps handle off-screen targets. Go to Pin for details.
When element clicked/tapped	Launches the experience when the user interacts with the specified element. Enter a CSS Selector or XPath path expression, or select Test and Preview to launch the visual selector.
After time on page/screen	Specify a delay (in minutes or seconds) that a user must spend on the page before they receive the experience.
Smart delay	Shows the experience after the user completes their current task.
Rage click/tap	Shows the experience after a rage click by the user. Amplitude considers a rage click to be rapid successive clicking or tapping in the same location.
User confusion Web only	Shows the experience when Amplitude detects user confusion, as signaled by the user's mouse movement.
On event tracked	Shows the experience after the user triggers an event that you define. The event must fire client-side so the Guides and Surveys SDK can observe it. Guides and Surveys doesn't support Labeled Events or Custom events as triggers. After you select an event, an After N occurrence(s) field appears under Select an Event. This field defaults to 1. Set it to a higher number to trigger the experience only after the selected event fires at least that many times in the current session. SDK version required for counts greater than 1: iOS/Android v3.7.0+, React Native v3.7.0+, Web (all versions). Guides and surveys with a count greater than 1 don't reach users on older mobile SDK versions. Go to the changelog. When you use this trigger with a survey, you can add Dynamic data blocks to capture event properties from the trigger event alongside each response.

Show on element click: use the SDK

To show a guide or survey when a user clicks a button or other element, the recommended approach is to set the trigger to None and call the .show SDK method from the element's onclick handler. This gives you precise control over which experience appears and when.

Trigger delay

For any trigger option besides Immediately, you can configure a delay (in seconds) before the guide or survey fires. Use a delay to make timing less intrusive. For example, show a survey five seconds after a user selects Checkout rather than the instant they click.

Previously, only the After time on page/screen trigger supported a wait. Trigger delay extends that capability to event-based, element-based, and other non-immediate triggers.

How to configure

In the nudge editor, open the Trigger section. After you select a non-immediate trigger, a Delay field appears. Enter the number of seconds Amplitude waits before firing the guide or survey.

Behavior

The delay countdown starts when the trigger condition first matches. If the user navigates away before the delay elapses, the guide or survey doesn't fire on the original page.
Delay is per-trigger. Different triggers on the same nudge can use different delays.
When you combine a delay with conditional logic (for example, "fire only when element X is visible"), Amplitude re-evaluates the condition at firing time, after the delay, rather than at trigger time.

Example

To show an NPS survey ten seconds after a purchase_completed event, set the trigger to On event tracked with the event purchase_completed, and set Delay to 10.

SDK requirement

Trigger delay requires a recent version of the Engagement Browser SDK. Update to the latest SDK release to use this feature.

Session properties

Session properties add a layer of trigger targeting restrictions for guides and surveys. When a guide or survey triggers and has session property conditions, all configured session property conditions must match for the experience to display.

The SDK sets session properties dynamically using the setSessionProperty method, and they can change throughout a user's session. Each value must be a string, number, or boolean. When a session property value changes, the SDK automatically evaluates whether any guides or surveys can now display, making session properties effective with the "Immediately" trigger.

Common use cases for session properties include:

User belongs to multiple orgs: Control guide or survey visibility based on features of the user's current organization (isFeatureEnabled: true).
Progress tracking: Show guides and surveys based on user progression (onboardingStep: 3).
Dynamic state that shouldn't persist as a user property: React to real-time user behavior or application state.

Feature availability

Session properties are a feature-flagged capability. Contact Amplitude support to use this feature in your implementation.

Where

Control whether your guide or survey displays on all pages, only specific pages, or excludes specific pages.

When you include or exclude specific pages, Amplitude accepts the following match types:

URL matches
URL/screen matches exactly
URL/screen matches pattern
URL/screen contains
URL/screen starts with
URL/screen ends with
URL/screen matches regex
Element CSS selector on page

Element CSS selector on page

Configure your guide or survey to display only when a specific DOM element appears on the page. Enter a CSS selector that identifies the target element. This match type evaluates when the trigger event fires.

You can use this rule for exclusion. For example: exclude pages where an element with the CSS selector .class-foo is on the page.

Combining page targeting rules

You can combine URL and element conditions using AND/OR logic. For example, you can display a guide when (a) URL contains /checkout AND (b) there's an element with .payment-success visible.

Project-wide default page exclusions

Set default page exclusions at the project level to apply them to every experience automatically. In the guides or surveys list, click the Settings icon and select the Guides tab to configure default page exclusions. Individual experiences can extend the project-wide default rules by specifying their own include or exclude rules in the Where section of the builder.

The same URL match types listed above (URL matches, URL contains, URL starts with, and others) apply to project-wide default exclusion rules.

Use project-wide exclusions when your app has pages where experiences should never appear, such as checkout flows, password reset flows, or error pages. Configuring exclusions once at the project level avoids repeating the same rules on every experience and prevents experiences added later from appearing on those pages. To hide every experience from a group of users instead of a set of pages, set project-wide default user exclusions.

Priority

Use priority to rank the importance of a guide or survey relative to others the user might encounter.

Urgent
High
Medium
Low

Tiebreakers when multiple guides are eligible for display

When more than one guide or survey is eligible for display at the same time, Amplitude uses these tiebreakers to decide which experience to show:

Active before inactive: Amplitude shows active guides or surveys before inactive ones. This tiebreaker only applies to guides or surveys that have Keep showing until completed or dismissed enabled. When that setting is disabled, a nudge is never active in this sense and skips to the priority tiebreaker.
Priority: Higher-priority experiences display first (Urgent > High > Medium > Low).
Most recently seen: If the user has seen one or more of the tied experiences before, Amplitude shows the experience the user saw most recently.
Most recently created: If the user hasn't seen either experience, or saw both at the same time, Amplitude shows the most recently created experience.

Prioritization table

Early Access

The new Prioritization table lets you order guides and surveys within a specific priority, so you can set a distinct order for every guide and survey. Sub-priority replaces rules 3 and 4 in the tiebreakers above.

Sub-priority is specific to each platform. Use the platform filter at the top of the prioritization view to switch to a specific platform (for example, Web, iOS, or Android) and set priorities and sub-priorities independently for each.

Sub-priority is also specific to form factor. These are the form factor groupings:

Modals, pins, and popovers
Checklists
Banners

Priority is irrelevant for tooltips and embeds. Tooltips and embeds always render if the targeting, trigger, and limits criteria are all met. Amplitude can render multiple tooltips and embeds simultaneously.

Limits

Limits prevent users from receiving too much messaging.

Limit	Description
Unpublish when X total responses received	Surveys only. When you enable this, Amplitude automatically unpublishes the survey after it receives the configured number of responses. The cap counts survey sessions, not individual answers. A user who answers several steps in one session counts as one response. Responses from test mode and preview don't count. The count includes responses from all users, not a per-user limit. The response count is cumulative and doesn't reset when you unpublish or republish the survey. If you re-publish a survey that has already reached the cap, Amplitude unpublishes it again when it receives the next response. Raise the cap before you re-publish if you need more responses.
Stop showing when completed	Enabled by default. When you disable this, the experience is eligible to trigger again through its trigger for the targeted users after the user completes it. To disable this option, you must also disable `Stop showing when dismissed`.
Stop showing when dismissed	Enabled by default. When you disable this, the experience is eligible to trigger again through its trigger for the targeted users after the user dismisses it.
Cooldown	When you enable this, it limits how often the experience can trigger for a user. Amplitude ignores cooldowns when (a) the experience is active or (b) the SDK, a button action, or a share link force-triggers it. To enable this option, disable `Stop showing when dismissed` first.

Localization

Localization lets you serve guides and surveys in different languages without creating a new guide or survey for each language. Refer to Localization for more details.

The Localization section of the Setup page shows your project's current localization settings, including the fallback behavior that applies when a translation is unavailable or outdated. These settings are read-only; use the link in the section to change them in project settings.

Content may not appear for some locales

When translation is unavailable and your project's fallback setting excludes that content, Amplitude skips the guide or survey for users whose locale has no uploaded translation. No error appears; the experience simply never displays. Refer to Configure fallback behavior if an experience isn't displaying for a subset of users.

Status

Statuses let you manage when your guide or survey displays.

Status	Description
Draft	Lets you make changes to and test the experience, but the experience doesn't appear to users.
Testing	The guide or survey can display to test users.
Published	The guide or survey is live. Any changes you make to a published experience appear to users after you save the guide or survey.
Scheduled	Define start and end dates during which your experience appears. Start and end times use the timezone set on your project.

If your project requires a reviewer to sign off before publishing, go to Approval workflows to configure approvers and request a review.

Bulk unpublish

To unpublish multiple guides or surveys at once, go to the Guides and Surveys list page, select the items you want to unpublish, and click Unpublish.

Common use cases include:

Unpublishing all active experiences before a demo or test run.
Unpublishing multiple versions of the same guide across different platforms at once.

Settings

Access guide or survey settings through the gear icon at the top of the builder. Some settings apply only on web. For a complete list, go to Mobile Guides and Surveys.

Setting	Description
Dismissable	Gives users an option to dismiss the experience.
Snoozable Web only	Lets the user snooze the experience for the specified duration.
Label Web only	The snooze button's text. Only visible when you enable Snoozable.
Duration Web only	How long the snooze lasts. The experience doesn't re-appear for the user until at least that much time has passed. Only visible when you enable Snoozable.
Snoozable on all steps Web only	If you disable this, the guide or survey's first step is the only step with a snooze option. Only visible when you enable Snoozable.
Searchable Web only	Makes the guide or survey findable through Amplitude's search functionality.
Available to Assistant Web only	Makes the guide or survey available for Amplitude's AI Assistant to surface to users.
Assistant intro Web only	Sets the introductory message the AI Assistant displays when surfacing this guide or survey.
Show step counter	Adds a step counter to each step in the guide or survey. For example, on a guide with five steps, the indicator `2/5` appears on the second step.
Searchable Web only	Lets users find this guide or survey from search.
Available to Assistant Web only	Lets Assistant surface this guide or survey in a conversation.
Assistant intro Web only	The text Assistant uses to introduce the guide or survey. Only visible when you enable Available to Assistant.

Active state

When a user first views a guide or survey, it becomes "active" by default. The guide or survey remains active until the user completes or dismisses it, and follows the user across page navigations even if the trigger condition is no longer met. For example:

A user sees a guide or survey on your homepage.
The user navigates to the contact page.
The guide or survey remains active even though the trigger condition didn't fire. The guide or survey follows the user to the contact page.

If Keep showing until completed or dismissed is disabled for the guide or survey in the example above, the contact page navigation ends the display. The guide or survey doesn't follow the user across pages.

When Amplitude temporarily hides a guide or survey, it doesn't show it to the user, but the guide or survey remains active. After the temporarily hide if conditions no longer apply, the active guide or survey is eligible for display again.

To disable active state for a specific guide or survey, turn off Keep showing until completed or dismissed in the Trigger section of the Setup tab. When disabled, the guide or survey stops appearing as soon as the trigger condition is no longer met and doesn't follow the user to other pages. This toggle isn't available for tooltips, which don't have an active state.

Was this helpful?