Events
This article explains Custom Events, Global Context, and Tracking Properties in PX.
Overview
When you install the Gainsight PX tag in your product, the code snippet automatically begins capturing and sending standard product usage events (session/visits, page loads, link clicks, and button clicks) to PX. In addition to these out-of-the-box events, PX provides several ways to enrich the data with more context so you can analyze usage in greater depth and tailor engagements more effectively.
These capabilities extend the baseline event data collected by PX and empower you to answer deeper product questions, build targeted segments, and design more personalized engagements.
To create and manage events, navigate to Administration> SET UP > Events.
The following tabs are available:
- Custom Events: Instrument specific product actions with additional payloads, such as email sends or searches, so you can track outcomes unique to your business.
- Global Context: Attach shared attributes (such as project, role, or environment) to all subsequent events in a session, making it easier to slice and analyze usage by meaningful dimensions.
- Tracking Properties: Capture contextual details directly from the product, such as URL parameters, UI element attributes, or system/browser information, without additional engineering effort.
Custom Events
Custom Events are valuable when product, UX, or CS teams want deeper insights into product usage. Unlike standard events, custom events can also carry contextual information, enabling a wide range of product-, business-, and goal-specific use cases.
Use Case 1
A product has a feature that allows users to send emails out. And, a custom event call would be made when a user sends the email out. The custom event not only states that the email was sent but it can include properties or payload such as number of targeted recipients, Is Test Send, and scheduled send day/time.
Gainsight PX collects these events with their associated properties and treats them as first-class events, making them available across the full PX feature set. For example:
- In-App Engagement: Immediately triggers an engagement that says Congratulations on your first email send. This looks like a test send, please refer to our other articles for more information...
- Email: Schedule a PX email to go out that congratulates users on their first send.
- Analytics: Provide deep analytics on how many email sends were sent to more than 1000 recipients or how many were test sends, and so on.
Use Case 2
Your product has some search capability. A custom event call would be made when one of your users performs a search, that will not only tell PX that a search event occurred but it can also include properties/payload such as the search term(s), number of results returned, page search performed against, and search filters, etc..
Just as before, PX would collect these events across their product’s usage allowing PX to do everything it was built to do. For example:
- In-App Engagement: If results = 0 then show dialog with tips on updating search criteria. If there are too many results, show dialog with tips, links to our knowledge base.
- Gainsight PX again would provide your team with deep analytics around not only how many searches were conducted but how many return with low results, high results to inform your product team on how you may want to better design the search algorithm or expose filters better.
To be clear, custom events are not code-free and will require your developer to sprinkle the custom event javascript call from the various locations of your codebase that you'll want to send to PX.
Create Custom Events
To create custom events:
- Navigate to Administration > Events.
- Click Add New. The Create Custom event window appears.
- Enter a unique name for the event.
- Select the type of event from the following options:
- Active: PX stores data from this event.
- Hidden: PX stores data from this event, but the event is not visible in the application.
- Dropped: PX does not store data from this event. Use this for legacy events or third-party events that do not need to be stored.
- In the Event properties section, configure the properties that must be tracked as part of this event.
Note: Custom events can also be created via API calls. For more information, refer to the Use Custom Event API article.
Global Context
Global Context lets product teams define contextual data that applies to subsequent events collected by the PX tag, such as page views, link clicks, and button clicks.
Note: You can only view the Global Contexts in your subscription from the Events page.
Use Case 1
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, and Project Z).
When the user chooses Project A, a Global Context call would be made to PX to say “OK, all events tracked from here on out, please associate with Project A”. Then, if user later switches to Project Z in the Project Management tool, the Global Context call would be made to PX to tell PX “OK, now any event you track from here on out, please associate with Project Z”.
This functionality has powerful benefits:
- Allows your team to slice and dice (dimensionalize) any of the tracked events (i.e. pages, button clicks, link clicks) by the various Projects (A, B, Z) allowing for deeper analytics. How many times has someone used feature A when working on Project A vs. B, etc.
- Eliminates duplicated data as the Project Name does not need to be included with every event.
- Allows for more targeted engagements. For example, you can specify that an engagement launch for only those who viewed this page under Project Z (and not Project A or B).
Use Case 2
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 logs in. Then, you can easily “slice/dice” or dimensionalize by the various Global Context values (How many marketers are using Feature A vs. How many from sales team are using that same Feature A).
Similar to custom events, making this call requires a developer to add the code to the various location of their code base that will determine when a context switch needs to occur.
Tracking Properties
The Tracking Properties tab provides a centralized view of all properties that have been created in Product Mapper. This view helps you quickly understand what properties exist, where they are being used, and who created them. These properties capture contextual details such as URL parameters, element attributes, or system values, that can be analyzed in PX Analytics.
Note: In the Tracking Properties tab, you can only view existing properties. To create new properties, use Product Mapper. For more information, refer to the Instrument Your Product using In-App Mapper article.
For each property, the following information is available:
- Name: Property name as defined in the mapper. Click to view property details.
- Description: Details about the property’s purpose.
- Data type: Format of the captured value (for example, String, Number, Boolean).
- Created at: Date and time when the property was created.
- Created by: Unique identifier of the user who created the property. Displays SYSTEM for out-of-the-box properties provided by PX.
- Used in: Usage count displaying how many features or rules are currently using this property. Click to view details in the Dependencies section.
- Delete: Remove a property, if it is not in use anywhere.
