Skip to main content
Gainsight Inc.

In-App Engagements FAQs

This article contains the Frequently Asked Questions (FAQs) related to in-app engagements.

Can I trigger an engagement when a certain feature is used OR not used?

Yes. Navigate to Create Engagement > Audience > Choose Product Mapper from a list of Trigger Rules available on the right > Choose Feature from the dropdown available > Set your criteria.

Can I stylize the engagements according to our branding?

Yes. Using WYSIWYG editor or CSS Code editor.

Can I preview the engagement before triggering?

Yes. By using Edit Guide In-App OR by clicking on the Preview button.

How do I test engagements?

You can do it in either of the following ways:

  • If you have PX Tag installed on your non-production environment, you can create and test engagements on the Non-Prod environment (OR)
  • Use Preview by navigating to Engagements > Editor > Edit in-app > Click on Preview (this will launch the engagement on your web app only as a Preview to you) (OR)
  • Create a Segment. Add Internal users who will be testing the engagement. Navigate to Create Engagement > Audience > Choose Segment from the list of Trigger Rules available on the right > Choose your Test User Segment > Trigger the engagement with other criteria in place only to Test Users; (OR)
  • Navigate to Create Engagement > Audience > Choose User’from the list of Trigger Rules available on the right > Choose email attribute from the dropdown available > Set your email id > Trigger the engagement only to yourself.
Once I set up with Audience Rules for my engagements, what is the importance of Qualification Scope?

Audience defines “Who” to target, Editor “What" to target, and Qualification Scope “When” to target. For example:

  • Every time a user logs in to your Web app.
  • Every time user triggers the engagement criteria.
  • Using a certain feature or only once in the user’s lifetime.
How to apply Audience Rules? I think Users, URL, Product Mapper, and Segments are the popular ones

The answer depends on the use case. See the following examples:

Users: You can use this rule in Audience when you want to target a specific set of users based on their user attributes. For example, User ID, Email ID, Role, etc.

URL: This rule should be used when one wants to trigger engagements on certain pages/ URL’s. “How many times” can be defined under Qualification Scope like every time, only once, and once per visit.

Product Mapper: This rule should be used when one wants to trigger engagements upon certain feature usage by end-users. For example, Trigger Engagement XX when feature AB is used/ not used.

Segments: This rule should be used mostly for targeting a specific cohort/ user group. For example, One has created a Segment for “Internal Users” or for “Test Users” or customers who were given training on a certain date. You can then target engagements to this group of users only.

In Qualification Scope, what would “Show 3 times every 2 months mean”?

If the Audience Criteria is met, the engagement is shown once every 2 months for 3 times if 'not completed' and then stops. If completed on 1st attempt, the engagement is not be shown again.

If there are multiple engagements triggered for a user, where do surveys fall in prioritization?
  1. Slider
  2. Guide
How soon can I view an engagement after it is launched?

All engagements are available 30 seconds after they are launched. You can view the engagement if you are included in the audience of the engagement and when you are qualified to view it.

When pausing a Guide engagement, the badge stays out there for a while, although clicking it does nothing. When will the badge disappear after the pause?

When you are pausing an engagement, the badge will be removed from the browser after 5 and a half minutes typically. This is because of a sync mechanism from the client every 5 minutes.

In a Guide engagement, which of the following is considered a view: seeing a hotspot or clicking a hotspot? 

Seeing a hotspot is considered a view. However for a Badge, that is triggered by a click and if the audience is everyone, a view is counted only when the user clicks on it.

Does the 'Skip Tour' button perform the same action as that of 'X' button? Does the user view the engagement after he clicks either of the buttons?

Yes, the 'Skip Tour' button performs the same action as that of 'X' button. The user will see the engagement again if the qualification scope is configured for multiple views.

How do I know when I need to include a URL in my Audience criteria (Single Page Application)?

Gainsight recommends defining URL rule in audience criteria in the following scenarios:

  • Include a URL in the Audience criteria if the engagements need to be triggered when a user lands on the page.
  • Use URLs for scoping the application areas. For a Single Page Application, the URL changes for different sections of the application. 

Best Practices

  • Use wildcard (*) patterns of the URL to trigger engagement on dynamic pages.
  • Exclude the sign in and sign out pages from the target pages for the engagement. As a safety mechanism, Gainsight PX SDK prevents matching guides from appearing in the wrong location in case the user signs out of the application.
What is the difference between using URL vs. Product Mapper while creating triggers in Audience segmentation?
Rule Description


Use this rule (User/ Account attribute) in Audience, to target a specific set of users based on their user attributes. For example, User ID, Email ID and Role.


This rule allows you to trigger engagements on certain pages/URLs. “How many times” can be defined under the Qualification Scope such as every time, only once, and once per visit. (inclusions/ exclusions)

Product Mapper

  • Behavioral/ contextual targeted: This rule must be used with certain mapped features, based on the past usage/lack of usage or being used by end users. For example, trigger engagement XYZ when feature ABC is used/not used.
  • Multiple features on the same page: You do not want the guide to appear simply when user navigates to the page but trigger when user clicks on a specific UI element.


Use this rule to target a specific cohort/user group. For example, you can create a Segment for internal users or for test users or customers who are part of the training on a specific date. 

Segment vs. Audience - when to use each to trigger a Guide?

Segments in PX allow you to create different audience/user groups based on common user/account attributes/parameters/ behavior. This feature is best used for defining data constant values. 

Note: Segment is not a way to filter historical usage data, you need to use audience filters to perform the same. Segment is a reusable target list - it is about manageability.

Use Segments for the following:

  • To test QA / internal user groups.
  • To achieve exclusion of groups / rules / URLs.
  • To target engagement for on-boarding cohort.
  • To reuse the Audience criteria in a series/multiple in-app engagements, NPS, CES, Multi Question Surveys, and in Funnel Analysis.
  • To refer to a list of elements such as account names/IDs and URLs.
  • To create a segment for a subset of your customers based on their lifecycle stage. For example, Free Trial Users, users who want to skip Product Releases, or for a set of customers who were part of a training/webinar.
Is there a way to use query parameters without the page having to refresh?

Depends on the navigation in your product/application. Gainsight PX supports displaying engagements when the user navigates to a specific section of the page using the engagement buttons and links. You can configure the engagement buttons or links to navigate to the section/page when clicked. 

How does the Intervals Qualification scope work?

The Intervals qualification scope allows you to display the engagement multiple times with recurring intervals during a specific time period. The advantage of this scope is that you can set a time gap between two views of engagement. The Interval schedule differs for Dialog and the other engagements. For more information, refer to the Intervals section of the In-App Engagement Qualification Scope article.

I can’t get my guide to show up in a certain scenario. How do I troubleshoot?

Basic Troubleshooting Steps:

  • Ensure that you using the right product. If you have multiple products, check if you have selected the right one.
  • Check the Schedule from the Date and Time Zone to ensure they are correct.
  • Ensure that the URL you are using matches the URL that the Audience Explorer > User Profile recognizes. Also, check other attributes/Test Segments/Identify.
  • Check the Audience criteria.
  • Check the number of views in In-App Performance/Analytics.

Advanced Troubleshooting Steps:

  • Verify if the Qualification Scope is Once per visit, and not Everytime.
  • Throttling  - Check if throttling is blocking the Qualification Scope.
  • Use Incognito or delete the Session ID - apt.sid and refresh the page to see if the engagement is launched. Perform the following steps:
    • Open DevTools in Chrome (Inspect) by pressing Control+Shift+J or Command+Option+J (Mac). 
    • Select the Applications tab and look for Cookies.
    • Search for apt.sid.
    • Delete the session from the X to the right of the search box.
    • Refresh your page to see if the engagement launches.
  • Ensure CSS Selection is correct and PX is able to locate it.
    • Check the Admin Console for suggested errors around CSS/ Browser.

If the above steps do not work, send an email to

How can I use the product mapper logic effectively to set the Audience criteria?
  • Use the OR logic when you want either of the features to trigger the guide as soon as the user accesses the feature:


  • Use the AND logic when you want to add all features:

Mapper 2.png


  • Both the rules perform the same function but in different approaches.
  • Audience Rules (a/b/c from the first image) AND (d/e from the second image).
  • Consider adding a module instead of adding all the features one by one. This means that if any of the mapped features within that module will trigger the guide based on the audience criteria.
What happens when there are multiple engagements that a user is qualified for?

Gainsight PX does not show more than one engagement to the user at a time to retain user experience. Engagements are shown to the users based on the following priority order: 

  • Slider
  • Guide
  • Dialog
  • NPS® Survey
  • CES Survey
  • Rating Survey
  • Boolean survey
  • Multi question Survey
Can I see multiple hotspots on the same page while each hotspot representing a different engagement with a different flow (hotspots and tooltips)?

No. Gainsight PX does not shows multiple engagements at the same time (i.e. same page) to retain user experience. You can see only one hotspot at a time. Once you finish the first guide or navigate away from the page, only then you can see the next hotspot.

Can I setup two engagements on the same page? For example: Explain a Feature when a user lands on a page, and then once the user finishes the task (and on the same page), display a survey engagement to the user asking for a “Rating”

Yes. You can achieve this use case by creating two engagements:

  • The first engagement will be the explainer that explains the feature (via hotspot, dialog, tooltips). You can use animated GIFs or videos to drive the explainer.
  • The second survey engagement can be set up to launch when the user completes the task. (i.e. set the audience to trigger when user clicks on the Save button or when they land on the ‘task completed’ landing page).
How clicks are measured in In-app engagements (Ex: Dialog)? What constitutes a click?

Only Clicks on links inside an engagement constitutes as a click and not buttons.

How can I reposition the badge in Guide engagements faster?

Gainsight PX provides you the option to set the time interval for badges to reposition faster with user actions such as window resizing or scrolls. Navigate to Administration > SDK Settings and specify the time (in milliseconds) in the Badge reposition response time (ms) field.

How can I configure tooltips to be responsive across different screens?

Gainsight PX provides you with an option to configure responsive tooltips as part of guide engagements. Navigate to Administration > SDK Settings and enable the Enable tooltips to be responsive based on viewport option.

When enabled, the position of the tooltips is dynamically adjusted based on the screen configuration.

Which takes precedence - Badge Qualification Scope vs. the Qualification Scope in the Engagement Schedule?

The badge qualification scope only evaluates whether to display the badge in the Guide engagement. The qualification scope in the Schedule section evaluates how often an engagement must be displayed to the qualified users.

NPS, Net Promoter, and Net Promoter Score are registered trademarks of Satmetrix Systems, Inc., Bain & Company and Fred Reichheld.
Can we change the pointer position for tooltip in Editor?

In the New Editor, you cannot change the pointer position for a tooltip. You can customize the tooltip alignment around the UI element by configuring the Coordinates Position. The pointer arrow auto-aligns based on the tooltip position you select. For example, 

  • If the tooltip is placed at the corner coordinates of the UI element, the arrow is positioned at corner of the tooltip.
  • If the tooltip is positioned at the middle coordinate, the pointer is in the center of the tooltip. 

The pointer cannot be moved to any other desired position on the tooltip.

What is the maximum number of emails IDs that can be listed at once in the Email field of Audience Logic?

In User Rule, you can list thousand emails IDs at once. For situations where you need to add more than a thousand emails, add one or more Email fields filter and list the rest of the email IDs. To add multiple email IDs in a filter, use comma and space as separators between the email IDs. For example:,, Use OR operator in the Rule Logic to configure the Email field filters.

  • Was this article helpful?