Use Global Context
This article explains the Global Context (aka Super Properties) feature in Gainsight PX.
Overview
In today’s analytics-driven world, the collection of usage data is a highly important task. Usage Data provides you key insights about how your customers are using your product. If the data collected is at a very granular level, it helps you better understand your customer’s behavior.
Global Context or Super Properties is a feature in Gainsight PX that allows you to collect data at more granular levels. You can set the levels of granularity as required. By default, PX collects all your usage data and stores it. You can use Global context to slice and dice the data and segregate it based on the required parameters. All the data tracked through Global context can be found in the Adoption reports page of the Analytics section.
Gainsight PX provides a specific API to accomplish Global Context-based data collection. You can configure this API as required.
Notes: The Global Context configuration varies based on the type of application you want to track using PX.
- For a single page application (SPA), you can set the Global Context value once and it remains same for all the subsequent events on the application until you either modify or delete the value.
- For a multi-page application, you need to set the Global Context value for each page to track the click/custom events on that page as the Global Context value does not survive a page refresh or a navigation to another page.
Use Cases for Global Context
-
A Project Management tool is using PX to track data (Page views, link clicks, and Button clicks). Users of the PM tool can log in and specify which project they are working on (Project A, Project B, etc).
When a user chooses Project A, global context can be set such that a message is sent to PX to say “categorize all the tracked data now under Project A ”. Later on, another user chooses Project B, global context informs PX to categorize all the events tracked under Project B, and so on.
You can now categorize PX Analytics data and view only those events that were recorded for Project A or Project B, and so on. You can understand which project has more clicks (which implies that users are having a hard time creating that type of project) and launch an engagement only on that project. When a user switches from one project to another, all their activities in the previous project are not overwritten to the new project (as in case of a standard attribute). -
Let’s say your product targets multiple personas. For example, your product may have features that can be used by sales and marketing teams.
You can set the Global context to be “Marketer” when a marketer logs in or “Sales” when sales employee logs in. You can easily analyze the data by the global context values and easily determine how many marketers are using Feature A as opposed to sales professionals. -
When you change the UI of your application, you can set a global context for the new UI. You can then compare user behavior for the new and previous UIs. You can easily infer as to whether the new UI increased the adoption of your product or not.
Advantages of Global Context
- Track different runtime elements like feature-flag, UI version, framework, and release version.
- Establish a sustainable instrumentation strategy.
- Gain greater visibility.
- Add context to the auto-tracked events that are specific to your organization.
Supported Data Types
You can define the Global Context as a set of Key-value pairs. The data types supported are:
- string
- number
- boolean
- datetime (ISO 8601 UTC date and time)
Configure Global Context API
This section provides a few examples of how you can use the Global Context API.
Set Global Context
You can use the following code to set the Global context to track UI version and runtime environment.
// Setting Global Context
// Track UI version and runtime
aptrinsic('set', 'globalContext', {"version":12345, "name":"Salesforce", "type":"Iframe"});
aptrinsic('set', 'globalContext', {"version":555, "name":"NXT"});
//Track an object:
aptrinsic('set', 'globalContext', {"projectId":12345,"Project Type" :"Work Order",
"Project Date":"2018-03-08T18:11:00Z" });
//
Update Global Context Values
After this call, all future events are populated with global context: projectId as 12345 and Project Type as Work Order.
You can use the following code to update the existing values of a Global Context API.
// Setting Global Context (Update a property)
aptrinsic('set', 'globalContext', {"projectId":67890});
//
Update only If Not Set
In the above example, the global context value for key "projectId" will now be 67890 for all future events.
You can use the following code if you wish to set a global context, only if it is not set previously.
// Setting Global Context (Check before update)
aptrinsic('setOnce', 'globalContext', {"projectId" : 45673})
//
Remove Global Context
In the above example, the global context for "projectId" remains 67890 and is not overridden by the second call.
You can use the following code to prevent events being tracked as Global Context. This does not impact the past events.
aptrinsic('remove', 'globalContext', ["projectId"])
//
Complex Example
The above example ensures that projectId is not tracked as a global context in the future events.
In the following example, the first call asssigns projectId as 67890 to the purchased custom event, but it will not be included as part of the second call.
aptrinsic('set', 'globalContext', {"projectId" : 67890});
//call custom event
aptrinsic('track', 'purchased', {"amount" : 1});
aptrinsic('remove', 'globalContext', ["projectId"]);
//call the same custom event again with different value
aptrinsic('track', 'purchased', {"amount" : 2});
/
Use case Example:
The following example helps you configure Global context code when you are using two versions of the same UI. In this example, the workspace version is passed as an argument that helps you filter reports by versions; v1 and v2.
aptrinsic('set', 'globalContext', {"workspace":'v1',"workspace Type" :"Work Order",
"workspace Date":"2018-03-08T18:11:00Z" });