Skip to main content
Gainsight Inc.

Instrument Your Product Using Product Mapper


The Product Mapper feature allows you to model your product using a simple and powerful hierarchical tree structure that is designed to help you quickly and effectively map your product’s features and associate the tracked user events into the corresponding features and modules with zero coding.

Modeling can be modified anytime time using a simple drag & drop!



Gainsight PX tracking code must be configured in your application. Refer to this 3 minute video on how to insert Gainsight PX code in your application.

Anatomy of Product Mapper

The Gainsight PX Product Mapper is made up of three elements; Module, Feature and Rules.


A Module in Product Mapper represents a module in your product which can be a section, tab or window of your application.

When modeling your product use modules and sub-modules driven by the way you describe your product and the way the UI is built. You can always modify it.
For example, in the below image you can see the Gainsight NXT product structure. It has the following structure:

Home, Timeline, Cockpit, Survey, Journey Orchestrator, Administration.GS_NXT app.gif

You can model this as tree structure within Product Mapper. You can create a Module for each section in the application (like Home, Timeline, Cockpit etc). The Home Module represents the Home section of the application, the Timeline Module represents the Timeline section of the application, and so on. All the modules together form a product tree of your application.


A Feature represents a feature in your product. Features consist of rules that are mapped to events from your application. There are three types of rules you can use in a feature:

  • URL Rule: A URL rule is used to track pageview event. In single page application, Gainsight PX will generate a pageview event on URL change even if the page is not reloaded.
  • Tag UI Element Rule: This rule tracks clickable elements in the UI by matching against the dom element using a unique CSS selector Text Capture Rule: tracks by matching against Text element on the screen, useful for SPA where there is no URL changes and no routing/URL parameters.
  • Custom Event: This rule tracks events fired via API. For more information refer to the Use Custom Event API article.

Automatic Instrumentation with Instant Mapper

The Instant Mapper helps you by suggesting a list of features and modules to be included in your product tree. Currently, Instant Mapper suggests only URL rule features to be included in your product tree based on pages visited by your users. The suggested features will automatically map to the feature hierarchy in your product while giving you the ability to accept the suggestion, modify its place by dragging and dropping, or choose to ignore the suggested features.

To view feature suggestions, turn on the Suggested features toggle button. When you turn the toggle switch, a list of features along with the modules are suggested.


To add a feature or module to the product tree:

  1. Switch on the Suggested features toggle button.
  2. Click Add to tree.

In the following image, the analytics module has eight features. When you click Add to tree for the Analytics feature, this feature is added to the Analytics module, since it was suggested to be under the Analytics module.


  • When you choose to add a suggested module to the product tree, all the features suggested under the selected module are also added to the product tree. 
  • When you choose to add only a single feature from a module, the other components of the module are not added to the product tree and only the selected feature and the module to which it belongs to, are added to the product tree.


The following image shows a sample suggested-signup module that has the following two components: 

  • signup feature
  • verifyemail module

Scenarios (sample)

  • When you click Add to tree for the signup module, the signup module, and both its components are added to the tree. 
  • When you click Add to tree only for the signup feature, the signup feature and the signup module are added to the tree. 
  • When you click Add to tree for the verifyemail module, the verifyemail module, verifyemail feature, and the signup module, are added to the product tree.

Manual Instrumentation in Product Mapper

This section explains the process of creating Modules and Features in Product Mapper to instrument features in your application. In this tutorial, the Gainsight NXT application is used to demonstrate the process of identifying Modules and Features. You must apply the same process to your application.

Create Modules

This subsection explains the process of creating Modules in Gainsight PX.

To create Modules:

  1. Click the Product Mapper icon from the left pane.
  2. Click Create module or select Add Module from the + New menu. This Module will represent the Dashboard section of the application.Create module.gif
    You can also use the icons at the right corner to create a new module or feature
  3. Type Home and press the enter key. A Module is created to represent the Home section.
  4. To created nested Modules, right-click the parent module and select Add Module.
    sub home.gif
  5. Repeat steps 2 and 3 to identify create all the modules which form a product tree of your application.

You can now see that the application is modeled into a product tree. This product tree has six modules ; Home, Timeline, Cockpit, Surveys, Journey Orchestrator, and Administration. Collectively the modules form the product tree of the application.

Identify Features

Once you identify Modules to represent your product structure, you must add Features for each module to track various metrics on your web page. This sub section explains the process of creating features in Product mapper.

Create URL Rule

This sub section describes how to create URL rules which track the number of page views.

To create URL rule feature:

  1. Right-click the Module for which the Feature must be created and select Add Feature.
  2. Type a name for the Feature and press the enter key.
    Home page_views.gif

This feature will track the number of times the Dashboard page has been visited.

  1. Right-click the Feature and select URL rule. An URL rule is used to track the number of times a page was visited.
  2. In the Scope window, enter the URL of the page to be tracked. In this example, the URL of the Dashboard webpage is entered. This tracks the number of pageviews for the Dashboard page.

In this case, whenever a user opens the above URL (accesses the Home page), the rule is matched and the count of number of Dashboard views is incremented by one.

You can use a Wildcard (*) to match multiple instances of a URl

You can also use wildcards to match a rule. Consider a scenario in which you have multiple URLs for the Home page (say Home/v1, Home/v2, Home/v3 etc), but all three URLs redirect you to the same Home page. In such cases, you can use the asterisk (*) wildcard to match all instances of the Dashboard URL, as shown below.

In this case, the Home page view is incremented, irrespective of the URL was used to access the page.

You can also use the wildcard at the beginning of the URL as shown below:

  1. (Optional) Click + Add to add multiple URLs. In this case, pageview is tracked only when user visits all the pages mentioned added in the above rule.
  2. Click Save.

Once a rule is created, the Feature icon color changes to Orange from grey.

pasted image 0-2.png

You can visit the page being tracked and then navigate to the Audience Explorer page to ensure that the newly identified feature is being tracked.

pasted image 0-3.png

If two or more UI elements of your application have the same name, you must instrument your strategy to hold the full path of the UI element. This process must be performed carefully as any typographical error in the name of any element in the hierarchical structure can prevent tracking of your element.

pasted image 0.png

When you map elements in hierarchical structure, Gainsight PX Analytics automatically rolls up the data from lower levels to higher levels.

Roll up.gif

In the above image, Create CTA and Delete CTA features are part of the Cockpit List View Module. You can view that the sum of their total events (5+4) is automatically rolled up and displayed on Cockpit List View module (9).

Create Tag UI Element Rule

This subsection describes how to create Tag UI Element rules. UI Element rules track the number of times a UI element (button) is clicked.

To create URL rule:

  1. Right-click the required module and select Add Feature.
  2. Enter a name for the feature and press the enter key.
    Home page export count.gifThis event will count the number of times the Export button (on the Home page) is clicked. You can analyze the number of times the specific page has been exported by users.
  3. Follow steps 1 and 2 to identify multiple features under the Audience Explorer Module or any other Modules.
    pasted image 0-1.png
  4. Click the Home Page Export count feature.
  5. Click Start Mapping.
  6. Enter the URL of the page on which the required button is located. (Here URL of Gainsight NXT application’s Home page).
  7. Click Launch.Home page exporter.gif

You are navigated to the URL. Here the target URL is Gainsight NXT’s Home feature. Hence, you are navigated to Home page. You can see that Product Mapper is now embedded on top of the Home page. You can configure UI Element rules from the application.

  1. From the Select feature drop-down menu, select the Home Page Export count feature. You must select the feature which you created in Step 2.
  2. Click Tag UI Element as feature.
  3. Select the EXPORT button. The Event window is displayed. The Scope page displays the URL of the page on which the button is located. It is very important to add the wildcard (*) on the Scope tab. The Selector tab displays the path used to reach the selected element.
  4. Click Save.
    MAP export button.gif

Create UI Element Rule Manually

You can also create UI Element Rules manually, by copying the CSS element code of the button.

To create UI Element rules manually:

  1. Right-click the required feature and select Tag UI Element.
  2. Enter the URL of the page on which the UI element tab is located.manual map.gif
  3. Navigate to the page on which the button is located.
  4. Right-click the required button and select Inspect.
  5. Identify the code block which contains the code for your button.
  6. Right click the code block and select Copy > Copy Selector.
  7. Return to the Gainsight PX site and paste the code (Ctrl + V).
  8. Click Save.
    Product mapper manual.gif

Mapping Menus

If you have sub menus and drop-down lists in your application, you can map them with “Tag UI Element” rule. When mapping a sub element, you must temporarily turn off the mapping to reach the required element. Once you select the “Tag UI Element” button, press ctrl+alt+m to disable mapping. Once you reach the desired location on UI, you can again press ctrl+alt+m to enable mapping.

mapping enablement.gif
Advanced Dom Tracking

You can configure the tracking code to use dom elements present in your application. For more information refer to the Advanced Instrumentation article.

Create A Custom Event Rule

A custom event is used to track those parts of your application which are not present on the UI. The steps to create a custom event rule are same (up to step 8) as in the  Create UI Element Rule section of this document.

To create a Custom Event Rule:

  1. Refer the Create UI Element Rule (initial 8 steps) section above.
  2. From the Select feature drop-down menu, select the required feature (here Home Custom Event). You must select the feature which you created.
  3. Click Custom Event Rule as Feature.
  4. From the drop-down menu, select the required custom event.The options displayed in the drop-down menu, are created by your developers.
  5. Click Save.Save element.gif

To learn about all frequently asked questions, refer Product Mapper FAQs article.


Gainsight PX allows you to perform a Backfill action on any mapped feature. With Backfill, you can choose a feature and execute historical data collection against this feature.


Important considerations about Backfill:

  • You need to perform Backfill for each feature individually.
  • The backfill process collects up to 365 days of historical data from all the events.
  • Backfill processing starts 15 minutes after the last feature Backfill request of a subscription.
    Each time there is a backfill request, Gainsight PX waits for 15 minutes before starting the actual Backfill process. If there is a new request for another feature of the same subscription during these 15 minutes, then this feature is added to the upcoming backfill processing. Another 15-minute wait window starts now. If no new feature Backfill requests are received during this wait window, then the Backfill processing starts.
  • A single Backfill request can work with multiple product trees.
  • When you click the Start Backfill button for a feature, an orange dot appears for the feature to indicate the ongoing Backfill process.
    Orange Dot Backfill.png
  • Backfill processing time can vary between 5 - 48 hours, after which the historical data appears in Analytics.
  • For instance, if you need to create a backfill for 10 features, then it is recommended to create Backfill requests for all the 10 features at the same time. 
  • If you edit the URL details of an existing feature in the Mapper and then perform backfill, the process adds the events but does not delete the historic events data. In this case, the best practice is to add a new URL rule event on the same feature as opposed to creating a new feature altogether. You can then delete the historic data if the data is irrelevant or if it overlaps with the new data.

URL Rule Event.jpg

  • Was this article helpful?