Instrument Your Product Using Product Mapper

Module

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. You can always modify it. For example, the following image shows the Gainsight NXT product structure with Home, Timeline, Cockpit, Survey, Journey Orchestrator, and Administration modules.

You can model this as a tree structure within Product Mapper. You can create a Module for each section in the application (like Home, Timeline, Cockpit, and so on). 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.

Feature

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 the 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.
• UI Text Element Rule: This rule tracks clickable elements in the UI with the additional match against the element's label (such as button label or text label), to identify elements when there are multiple UI elements with similar CSS.
• Custom Event: This rule tracks events fired via API. For more information refer to the Use Custom Event API article from the Additional Resources section.

Floating Mapper 

Gainsight PX helps you to adjust the position of the pane of the Product Mapper while mapping the UI elements. The floating mapper provides you with the flexibility to place the mapping pane on the top or bottom of your application so that it does not obstruct your view or interfere with the application. The Product Tree structure of the in-app mapper aims at making the mapping easier and more streamlined.

To use this enhancement, admins need to navigate to Administration > SDK Settings and turn ON the Enabling Floating Editor Mode option.

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 +New and select Module from the menu. This Module will represent the Dashboard section of the application.
   You can also use the icons in the right corner to create a new module or feature.

3. Type the module name in the text box that appears and press the enter key. A new Module is created.
4. To created nested Modules, right-click the parent module and select Module from the Add New menu options.

5. Repeat steps 2 and 3 to identify create all the modules that form a product tree of your application on the left pane.

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

Identify Features

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

Create URL Rule

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

To create a URL rule feature:

1. Right-click the Module for which the Feature must be created and select Feature.
2. Type a name for the Feature in the text box and press the enter key.

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

3. Right-click the Feature and select URL rule. An URL rule is used to track the number of times a page was visited.

4. 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 the 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:

5. (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.
6. Click Save.

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

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.

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 the tracking of your element.

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

In the above image, Survey List URL Rule and Add Survey features are part of the Survey List Module. You can view that the sum of their total events (476 + 160) is automatically rolled up and displayed as Total Events of the module (636).

Tag and Create Feature 

Use the Tag & Create Feature button to tag UI elements and create features in Product Mapper. This brings a unified rule creation capability for CSS selectors and texts.

1. Click Start Mapping.
2. Enter the URL of the page on which the UI element is located. 
3. Click Launch. You are navigated to the URL. You can see that Product Mapper is now embedded on top of the target web page.
4. Click Tag & Create Feature.
5. Click on the desired UI element to be mapped. A New Feature window displays.
6. Configure the Scope and Selector details of the feature, if you want to modify the default settings.
7. Click Save. The element is mapped as a feature in Product Mapper.

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 in the text box and press the enter key. This 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.
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.

You are navigated to the URL. Here the target URL is Gainsight NXT’s Home feature. Hence, you are navigated to the 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.

8. 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.
9. Click Tag UI Element as feature.
10. 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.
11. Click Save.

Create UI Text Element Rule

This subsection describes how to create UI Element Text Match rules. Text match rules against the element's label (such as button label or text label), to identify an element when there are multiple UI elements with similar CSS.

To create the UI Text Element rule:

1. Click the Product Mapper icon from the left pane.
2. On the Product Feature Tree ® page, click on the feature.
3. Click Start Mapping.
   Note: Alternatively, you can also click on the UI Text Element button on the top right corner to define the URL and element text rule from the PX application.  
4. Enter the URL of the page on which the required UI element exists.
5. Click Launch. You are navigated to the target page and the in-app Product Mapper options are displayed on top of the page.
6. From the Select feature drop-down menu, select the feature.
7. Click on the UI Text Element rule icon.
8. Click on the UI element that must be tracked when clicked. The Event window is displayed. 

Notes:

• The Scope tab displays the URL of the page. Add the wildcard (*) to the URL.
• The Text Element tab displays the path to the selected element.

9. Click Save.
10. Click Exit to navigate to the PX application.

Note: Features Mapped using the UI Text Element rule are not eligible for Backfill.

Create Custom Event Rule

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

To create a Custom Event Rule:

1. Refer to 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 the 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.

To learn about all frequently asked questions, refer Product Mapper FAQs article from the Additional Resources section.

Create Labels for Features and Modules 

You can create labels to organize product features and modules in Product Mapper. The labels make it easier to select a group of relevant features to create analytics reports or to export feature usage data via integrations.  You can use the labeled features to build queries using Query Builder and to export feature usage data using Data Export.

To create labels:

1. On the Product Feature Tree ® page, click on the feature/module for which you want to create the label.
2. Click the Add Labels icon.
3. Click Create Labels. The Create Label window appears.
4. Provide the details and click Create. The label is created.

Notes:

• You can add a maximum of 10 features or modules to a label.
• You can create a maximum of 20 labels per product.

For more information on creating Data Exports using labels, refer to the Bulk Export Custom Reports from PX article from the Additional Resources section. For more information on building queries using feature labels, refer to the Query Builder article from the Additional Resources section.

View Mapped Features and Product Tree Path

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

You can view the full path of feature/module names in the search results dropdown list in Product Mapper. This helps to select the right feature or modules, especially in scenarios where there are similar feature names within different modules.

Limitations

Gainsight PX has defined limits to the number of features and modules that can be mapped. The following are the limits:

At the subscription level (across all the products):

• Features - A maximum of 10000 features and modules can be mapped.
• Feature Rules - A maximum of 10000 rules can be created.

At the product level:

• For the Enterprise plan - A maximum of 5000 features can be mapped.

• For the Essential plan - A maximum of 3000 features can be mapped.