Skip to main content
Gainsight Inc.

Instrument Your Product using In-App Mapper

  1. Last updated
  2. Save as PDF

This article explains how to use In-App Product Mapper as a modeling and instrumentation tool.

Overview

Product Mapper 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.

Prerequisite

To use Product Mapper, ensure that the Gainsight PX tracking code is configured in your application. Anatomy of Product Mapper. For more information, refer to the Install Gainsight PX on Your Web App article.

Instrument Your Product

Product Mapper is an easy to use way of describing your product features with a simple point-click-describe method. Modules and features can be organized to match your application. For example, you can organize by modules and features or you can nest sub-modules under modules and add features at any level. 

To map your application:

  1. Navigate to Product Mapper from the main menu. 
  2. In the Map Product In-App section, click Get Started. 
    Landing Screen.png
     
  3. In the Launch In-App Product Mapper window, enter the URL of your product. 
  4. Click Launch. Gainsight PX displays the In-App Mapper in your application.

in-app mapper_annotatde.png

In-App Product Mapper helps you organize your product's features into a hierarchical tree structure directly on your application’s interface, for a seamless user experience. To instrument your product: 

  1. Add modules
  2. Add features

For demonstration purposes, the following demo application is used to demonstrate the process of identifying modules and features. Gainsight PX recommends applying the same process to your application.

Demo website.png

Add Modules

A Module in Product Mapper represents a module in your product which can be a section, tab, or window of your application. While modeling your product, use modules and sub-modules driven by the way you describe your product and the way the UI is built.

To create Modules:

  1. In the floating mapper, click the Add button and select Module.
    Add nodule.png

  2. Enter the module name and press Enter. A new module is created.
  3. (Optional) To create nested modules, click the Edit icon of parent module and select Add Module.
  4. Continue to add modules or sub-modules corresponding to sections of your application.
    Add Module_added.png

You can see that the application is modeled into a product tree. This product tree has many modules; Dashboards, Charts, Tables, and so on. Collectively the modules form the product tree of the application.

Add Features

A feature in Product Mapper represents a feature in your product. Once you have added modules, you need to add features for each module to track various metrics on your web page. The In-App Mapper provides you with an easy click-and-tag experience to map  UI elements and create features in Product Mapper. 

While using the In-App Mapper, you can tag and create features using either of the following ways:

Add Feature to a Module

Adding a feature nested within a module helps you add multiple features of your product that may reside on the same page or section. 

To add a feature:

  1. In the product tree, click the Edit icon of the parent module. 
  2. Click Add Feature.
    Add Feature.png
     
  3. Enter the feature name and press Enter. A new feature is created.
  4. Continue to add features for modules or sub-modules corresponding to your application.
    Add Feature_Added.png

Adding a rule directly as a feature allows you to create features that are not part of any module or sub-module, and have to be tagged independently. Such rules will be created at the parent level (level zero) of the feature tree.

Business Scenario Example: Consider you have a universal search present in the header of your application, and you wish to track each time the search box is clicked. Since the search box appears across your application, you may want to track it independently, without tagging to a specific module. For such a scenario, you can create a UI Element rule as a feature.

To add rule as a feature:

  1. In the floating mapper, click the Add button and select the rule you wish to create. Ensure that there is no item selected in the product tree.
    Add rule as feature.png

  2. Create and save the rule to add it as a feature in the tree. For more information on how to create rules, refer to the Add Rules section.

Add Rules

Features consist of rules that are mapped to events from your application. The following are the types of rules you can use in a feature:

  • URL Rule 
  • UI Element Rule

URL Rule

A URL rule is used to track the pageview event. In a single-page application, Gainsight PX generates a pageview event on URL change even if the page is not reloaded.

To create a URL rule:

  1. In the product tree, select the feature in which you want to create the rule.
  2. In the floating mapper, click the Add button and select URL Rule.
    Add URL Rule_1.png
     
  3. Enter a name for the rule.
  4. In the URL Details section, enter the URL of the page to be tracked. In this example, the URL of the Charts page is entered. This tracks the number of pageviews for the Charts page.
    Add URL Rule_2.png

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

Quick Tip: Use Wildcards for multiple instances of a URL. Click to expand.
You can use a Wildcard (*) to match multiple instances of a URL. Additionally, you can also use wildcards to match a rule. Consider a scenario in which you have multiple URLs for the Home page (for instance, Home/v1, Home/v2, Home/v3 and so on), but all three URLs redirect to the same Home page. In such cases, you can use the asterisk (*) wildcard to match all instances of the Home URL, as shown below:

wildcard.png

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

You can also use the wildcard at the beginning of the URL in case you have multiple instances of the URL.

  1. (Optional) Click + to add multiple URLs. 
  2. In case of multiple rules, define the logic from the Operator field.
  3. Click Apply. The rule is created in the selected feature. Click Rules to view all rules created for the selected tree item.
    Add URL Rule_3.png

UI Element Rule

The UI Element rule tracks the number of times a clickable UI element (such as button) is clicked by matching against the DOM element using a unique CSS Selector. In-App Mapper allows you to click-and-tag UI elements to create accurate rules. This brings a unified rule creation capability for CSS selectors and texts.

Create UI Element Rule

To create a UI Element rule:

  1. In the product tree, select the feature in which you want to create the rule.
  2. In the floating mapper, click the Add button and select UI Element Rule. Alternatively, you can press Control + M on the keyboard to start mapping.
  3. Click the UI element you want to use for the rule.
  4. In the UI Element Rule window, enter a name for the rule. 
  5. In the UI Element Details section, verify the CSS selector chosen based on the UI element clicked.
  6. (Optional) Click Show Advanced Selector Configurations if you wish to select a different CSS selector or enter a custom one. 
  7. (Optional) Click Change Mapping if you wish to change the UI element tagged to the rule.
  8. Click Apply. 
Create UI Element Rules with Text Matches 

You can use the Text Match option to create features with CSS plus text match. This helps in preventing applications with dynamic UI elements from experiencing CSS selector match issues, and provides flexibility to map the unique elements faster.

To create a UI Element rule with text match:

  1. In the floating mapper, click the Add button and select UI Element Rule. Alternatively, you can press Control + M on the keyboard to start mapping.
  2. Click the UI element you want to use for the rule.
  3. In the UI Element Rule window, enter a name for the rule. 
  4. In the UI Element Details section, verify the CSS selector chosen based on the UI element clicked.
  5. (Optional) Click Show Advanced Selector Configurations if you wish to select a different CSS selector or enter a custom one. 
  6. Enable the Text Match Details toggle switch.
  7. Select the logic identifier and enter the text to be matched.
  8. (Optional) Click Change Mapping if you wish to change the UI element tagged to the rule.
  9. Click Apply. 

Note: Rules created using the Text Match option cannot be backfilled.

Create Rules with Only Text Matches 

You can use the Text Match option to create features solely with text match. This helps in preventing applications with dynamic UI elements from experiencing CSS selector match issues, and provides flexibility to map the unique elements faster.

To create a UI Element rule with only text match:

  1. In the floating mapper, click the Add button and select UI Element Rule. Alternatively, you can press Control + M on the keyboard to start mapping.
  2. Click the UI element you want to use for the rule.
  3. In the UI Element Rule window, enter a name for the rule. 
  4. In the UI Element Details section, turn off the UI Element Details toggle. 
  5. Enable the Text Match Details toggle switch.
  6. Select the logic identifier and enter the text to be matched.
  7. (Optional) Click Change Mapping if you wish to change the UI element tagged to the rule.
  8. Click Apply. 

Note: Rules created using the Text Match option cannot be backfilled.

Filters in Product Feature Tree

Filters on Product Feature Tree allow you to quickly find what you need by narrowing down your product tree using multiple criteria such as Tree Items (empty or non-empty modules and features, Modified by, Labels, and Rule Type.

Filters in in-app mapper.png

View Mapped Features

Product Mapper has a Show Mapped Features option that helps you view the features mapped already in your application. This helps in identifying the features that are yet to be mapped, thus avoiding duplicate mapping.

Additional Resources