Instrument Your Product Using Product Mapper
This article explains how to use the Product Mapper modeling & instrumentation tool.
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.
- 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.
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.
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.
Use 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.
This subsection explains the process of creating Modules in Gainsight PX.
To create Modules:
- Click the Product Mapper icon from the left pane.
- Click Create module or select Add Module from the +New menu. This Module will represent the Dashboard section of the application.
- Type Home and press the enter key. A Module is created to represent the Home section.
- To created nested Modules, right-click the parent module and select Add Module.
- 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.
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:
- Right-click the Module for which the Feature must be created and select Add Feature.
- Type a name for the Feature and press the enter key.
This feature will track the number of times the Dashboard page has been visited.
- Right-click the Feature and select URL rule. An URL rule is used to track the number of times a page was visited.
- 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 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:
- (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.
- Click Save.
Once a rule is created, the Feature icon color changes to Orange 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 tracking of your element.
When you map elements in hierarchical structure, Gainsight PX Analytics automatically rolls up the data from lower levels to higher levels.
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:
- Right-click the required module and select Add Feature.
- Enter a name for the feature 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.
- Follow steps 1 and 2 to identify multiple features under the Audience Explorer Module or any other Modules.
- Click the Home Page Export count feature.
- Click Start Mapping.
- Enter the URL of the page on which the required button is located. (Here URL of Gainsight NXT application’s Home page).
- Click Launch.
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.
- 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.
- Click Tag UI Element as feature.
- 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.
- Click Save.
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:
- Right-click the required feature and select Tag UI Element.
- Enter the URL of the page on which the UI element tab is located.
- Navigate to the page on which the button is located.
- Right-click the required button and select Inspect.
- Identify the code block which contains the code for your button.
- Right click the code block and select Copy > Copy Selector.
- Return to the Gainsight PX site and paste the code (Ctrl + V).
- Click Save.
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.
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:
- Refer the Create UI Element Rule (initial 8 steps) section above.
- From the Select feature drop-down menu, select the required feature (here Home Custom Event). You must select the feature which you created.
- Click Custom Event Rule as Feature.
- From the drop-down menu, select the required custom event.The options displayed in the drop-down menu, are created by your developers.
- Click Save.