Setup and Targeting
Guides and Surveys offer targeting and triggering options to ensure your guide or survey appears when it should, to whom it should.
Navigate to the Setup tab in a guide to access these options.
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.
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.
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 bucketing is based 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.
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.
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. |
| 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. |
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 be met for the experience to display.
Session properties are set dynamically through the SDK using the setSessionProperty method, and can change throughout a user's session. When a session property value changes, the SDK automatically evaluates whether any guides or surveys can now be shown, 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.
Page targeting rules can be combined
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.
Priority
Use priority to rank the importance of a guide or survey relative to others the user might encounter.
- Urgent
- High
- Medium
- Low
Prioritization
When more than one guide or survey is eligible to display to a user, the highest-priority experience displays.
Amplitude breaks prioritization ties using these tiebreakers in order:
- 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.
Limits
Limits prevent users from receiving too much messaging.
| Limit | Description |
|---|---|
| Stop showing when completed | Enabled by default. When disabled, the experience is eligible to trigger again through its trigger for the targeted users after the user completes it. Disabling this option requires Stop showing when dismissed to be disabled. |
| Stop showing when dismissed | Enabled by default. When disabled, the experience is eligible to trigger again through its trigger for the targeted users after the user dismisses it. |
| Cooldown | When enabled, limits how often the experience can trigger for a user. Amplitude ignores cooldowns when (a) the experience is active or (b) force-triggered by the SDK, a button action, or a share link. Enabling this option requires that Stop showing when dismissed is disabled. |
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.
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. |
Settings
Access guide or survey settings through the gear icon at the top of the builder.
| 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 Snoozable is enabled. |
| 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 Snoozable is enabled. |
| Snoozable on all steps Web only | If disabled, the guide or survey's first step is the only step with a snooze option. Only visible when Snoozable is enabled. |
| 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. |
Active state
When a user first views a guide or survey, the guide or survey becomes "active". The guide or survey remains active until the user completes or dismisses it. 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 wasn't met. The guide or survey follows the user to the contact page.
If a guide or survey is temporarily hidden, Amplitude doesn't show it to the user, but the guide or survey remains active. After the temporarily hide if rules are no longer met, the active guide or survey is eligible for display again.
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.
- 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.
Was this helpful?