Skip to main content
Gainsight Inc.

Anatomy of Engagements

​This article explains different types of engagements and configurations to launch your engagements.


Engagements in PX allow you to launch in-app announcements, provide tooltips, send automated emails, and surveys. PX supports five types of Engagements. This article introduces each engagement type and explains the configurations which are common to each type of engagement.

Engagement Sections

PX engagements consist of five sections. These sections are common to each of the five types of engagements. The five sections are explained below:


The Audience section allows you to select your target audience, or who can view the engagement. You can create rules to match your requirements.

For example, the below rule ensures that the engagement is displayed only to the user with the specified email ID, and who resides in the United States as the AND logic is selected. You can use the AND or OR logic within a rule, to configure multiple parameters. Click + Add to add multiple parameters.

Anatomy of engagements.jpg

Gainsight PX supports the following rules that you can use with logical operators to define your target audience. 

Rule Usage
Users To set target users who can view the engagement.
Account To set target Accounts (customers) that can view the engagement.
In-App Engagement To use another engagement as a parameter. For example,

For example, you can push a feature enhancement to a customer via an email. Insert clickable link "" in the email, engagement rules will read the values and display the guide engagement with the new feature description.

Product Mapper To use features from the Product Mapper as parameters.
NPS Survey To use the NPS Survey response of a user as a parameter. 
CES Survey To use the CES Survey response of a user as a parameter. 
Rating Survey  To use the Rating Survey response of a user as a parameter. 
Boolean Survey To use the Boolean Survey response of a user as a parameter. 
Query Parameters To customize the content for the values passed in URL.

For example, you can share a feature enhancement to a customer via an email. Insert clickable link "" in the email, engagement rules reads the values and display the guide engagement with the new feature description.

In-App Engagement 

To deliver targeted and personalized email engagements to the qualified users based on their specific interactions with the application. 

For example, if a user has not used a specific feature (by not viewing a targeted In-App engagement) for a long time and needs to be intimated, an email can be automatically triggered and sent to the qualified user.

Inferred Company To use an account’s inferred location as a parameter.
Inferred Location To use a user’s Inferred location as a parameter to create the rule.
Account Location To use an account’s location as a parameter to create the rule.
Location To use a user’s location as a parameter to create the rule.

To use a page URL as a parameter.

Note: URL rule is case sensitive. For example, Gainsight PX considers '/udp/reports' and '/udp/Reports' as two different pages when filtering the audience.

Device To use a specific device (Mobile, Desktop) as a parameter.
Platform (OS) To use an operating system as a parameter.
Browser To use the browser as a parameter.
Browser Language To use a language supported by a browser, as a parameter.
Referrer To use a referrer as a parameter.
Custom events To use custom events as parameters.
Global Context To use a Global Context filter (created in Adoption Report) as an engagement rule. For more information about the Global Context, refer to the Global Context API article from the Additional Resources section.
Segments To use segments as parameters. For more information about segments, refer to the Segments article from Additional Resources section. 


PX offers a library of engagement templates. Templates are categorized into the following tabs:

  • Saved Templates: Displays the list of your saved templates.
  • Default Templates: Displays the list of default templates, provided by PX.
  • Recently Used: Displays the list of your recently used templates.  

If you have multiple PX subscriptions and want to share the templates across these subscriptions, refer to the Share Engagement Templates Across Subscriptions section of the Install Gainsight PX on Your Web App article from the Additional Resources section.

Select template for your engagement 

Choose the template of your choice from the default or existing templates for the engagement. This is an optional step. 

To use the default or existing template:

  1. Navigate to the Templates section.
  2. Hover on the template and click Preview. 
  3. Click Use. You are navigated to the Editor section.

Default Template.png

Create engagement without using template

  1. Navigate to the Editor section.
  2. Click New Device Content.
  3. Select the Device Type
  4. Click Create. Configure the engagement using the Editor tab.

Anatomy of Engagements - Gainsight Inc. 2023-05-29 at 2.57.41 PM.jpg


Use the Editor section to create content for your engagement, add images, videos, use text editors, add hyperlinks. You can do the following in the Editor section:

  • Edit Engagement content 
  • Add images
  • Add Tokens
  • Edit Size, Background, and Navigation options
  • Edit View Type, Position, Overlay color, and Behavior
  • Edit CSS content in Engagement
  • Preview, Save, and Delete Engagement

Edit Engagement Content

The Editor section provides text editors which you can use to apply text effects (bold, italic underline), hyperlink a word in your engagement, change font size and color, add images, embed videos, add buttons, and many more.

Editor eng.png

Add Images

Add images to your engagements to make it visually appealing to the viewers. To add an image, click the Insert Image icon from the Editor tab. 

Note: The maximum file size for an image or GIF that can be uploaded is 5MB. 

Editor Image.png

Following options are available to Add an image:

  • By URL: Enter the URL of a web image that you want to add.
  • Browse: Choose an image from the library of images that are already uploaded or used in the subscription.
  • Upload Image: Upload an image from your computer to the engagement.

After you add the image, click on it to use the options like Display, Style, Size, Align and many more.

Editor image_2.png

Add Tokens

You can add tokens in your engagements. Gainsight PX automatically resolves tokens with their respective values, when you launch the engagement. You can use fields from the User or Account object to create tokens. 

Anatomy of Engagements - Gainsight Inc. 2023-05-29 at 3.02.08 PM.jpg

Modify the size of your engagement (not applicable to Email engagement), background color of engagement, and set the navigation path for the engagement. These options are available on the Editor tab and vary based on the engagement.  

Editor Engagement.png

The options highlighted in the above image are applicable only to a Dialog engagement.

Edit View Type, Position, Overlay color, and Behavior

Set the position and appearance of your engagement and timeout for the engagement on the target application page. These options are available on the Settings tab, and are not applicable for an Email engagement. 

Following options are available for you to configure:

  • View Type: Allows you to select a Dialog or Bar view for your engagement.
  • Position: Option to place your engagement at the required position on the target application page.
  • Overlay: Places a colored overlay on the target application page, underneath your engagement.
  • Behavior: Allows you to set a time frame after which the engagement is not displayed. 

Settings Editor.png

The above option shows the engagement in the top right corner of the target application page, with Dialog view type, in the selected Overlay color (red). The dialog disappears after 5 seconds, as set in the Behavior section.

Edit CSS content in Engagement

The CSS view is displayed on the fourth tab of the engagement. You can edit CSS content for each step of the Guide/Slider/Survey/Multi-Question Survey Engagements separately. This does not apply changes to the entire engagement. The step CSS takes precedence over the engagement CSS. For example, in the engagement CSS if you set the content text color as Red, and in the step CSS you set the color as Blue, the text color is displayed in Blue.

The following tabs are available under CSS:

  • Step: Editable CSS for the selected engagement step 
  • Slider/Guide/Survey: Editable CSS for the entire engagement 
  • Default: Non-editable default CSS

CSS Editor.png

From the CSS view, you can customize the font for the header title and content in the engagement step. For example, to customize font for the header of a slider step, you can add the 'font-family: <<Font-Name>>' property in the '.px-slider-content-header' class in the Step tab. For more information on the CSS Styling, refer to the Use Templates article from the Additional Resources section.

After updating the CSS, you can save the template with styling changes to use it in new engagements. For more information on how to save the engagement as a template, refer to the Preview, Save, and Delete Engagement section.

Preview, Save, and Delete Engagement

After you finalize the appearance and content of your engagement, save and preview the engagement on any page of your application. You can also save the engagement as a template.

Save Engagement As Template

To save an engagement as a template:

  1. Click the save as Template icon.
  2. Enter a name for the template.
  3. Click Save.
  4. Navigate to the Saved Templates tab in the Templates section to view your template.
    Note: Hover on the template and click the Delete icon to delete the template.
Preview Engagement

To preview an engagement:

  1. Copy the URL of your application page on which you want to preview the engagement.
  2. Click Click to Preview. The Preview window is displayed.
  3. Paste the application page URL.
  4. Click Launch.

Anatomy of Engagements - Gainsight Inc. 2023-05-29 at 3.05.18 PM.jpg

Tip: If your content is very close to the border of the engagement, increase the width of your engagement from the Editor tab.

Delete Engagement

Gainsight PX provides you the option to delete the engagements that you no longer use to avoid clutter on the engagement list page. You can delete an engagement in the following ways:

  • From the engagements list page, click the three-vertical dots icon for the required engagement and click Delete. OR
  • From the engagement details screen, click on the Trash icon.

Schedule your engagement to define when and how it should be evaluated and triggered. In-app scheduling differs from email scheduling due to the different nature of these engagement channels, for example Email can be a great way to reach out to users after they are no longer in your app and driven by a predefined schedule whereas in-app will always be triggered by users when using the app.

For more information about Engagement Scheduling and qualification scope, refer to the In-app Engagement Qualification Scope article, and for the Email Engagement Scheduling, refer to the Email  Engagement Qualification Scope article from the Additional Resources section.

Engagement Throttling Settings

The engagement throttling setting controls how often the engagement is displayed to the qualified users in your application. 

Note: Throttling settings are applicable:

  • Only to in-app engagements both existing and new engagements.
  • Only in the Production environment of Gainsight PX. 
  • For all trigger types - Automatic, KC and JO.

PX supports the following throttle settings:

  • Minimum time gap between engagements: To set the time between two engagements. If you set the minimum time gap to 30 minutes, users who are qualified to view multiple engagements can see each engagement within 30 minutes.
  • Maximum engagements shown in a Day/Hour/Minutes: To set a limit on the maximum number of engagements that a user can view in the specified hours, minutes, or days.

To configure the throttling settings:

  1. Navigate to Administration > Throttling.
  2. Turn ON the toggle switch in At least and At most sections.
  3. Set the time and number of engagements to be shown parameters.
  4. Click Save.

Engagement throtling anotomy.png

Example Business Use Case

When a user is qualified to view multiple engagements that are targeted on the same page, the engagements appear one after the other and could overwhelm the user. This feature allows you to set the throttle limits, such as one engagement every 20 minutes, or a maximum of 5 engagements in a week.

If an engagement is critical and must be communicated on priority (for example, application maintenance message), you can select the Ignore global throttling settings checkbox in the Schedule section of the engagement to override the global throttling settings.



The Launch section displays a summary of all the configurations for your engagement. You can launch an engagement or pause a launched engagement from this section.

In case of a configuration error in the engagement section, an exclamation (!) is displayed next to the respective section and the Launch section. You can launch an engagement only if all the sections have a checkmark next to them.

Launch Engagement.png

You must select the environment(s) to which you want to launch the engagement. For more information about the environment settings, refer to the Gainsight PX Environment Settings article from the Additional Resources section.

Trigger the Engagement

Trigger your engagement either on the application page and/or in the Knowledge center bot. Following triggering options are available:

  • Automatic: The engagement is displayed only on those application pages which you select in the Audience section.
  • Knowledge Center: The engagement is displayed only in the Knowledge Center bot.

trigger engagement.png

Note: If you choose to trigger an engagement by both the options Automatic and Knowledge Center, the engagement is visible on the selected UI and also on the KC bot.

Trigger by Badge

Use the badge icon to trigger a Guide engagement. The guide starts to play when the user clicks on the badge icon. 

Badge engagment.png

Trigger by Journey Orchestrator

Trigger an in-app engagements such as Dialog, Slider, or Guide engagement from Gainsight’s Journey Orchestrator (JO) module. This feature is available only to the customers who use both the CS and PX applications. When you trigger an engagement from JO, you can use it in the JO module. For more information about the configurations to be performed in JO, refer to the Trigger PX In-app Engagements from Journey Orchestrator article from the Additional Resources section. 

Engagement JO.png