When viewing visitor and account metadata in Pendo, you can see details related to the last event Pendo processed for a visitor. If you want to view historical data to better understand the context for how a visitor or account was using your app when a Feature, Page, Track Event, or Guide Event was recorded, you can enable historical metadata.
When you update your user metadata as historical metadata, this allows the data to also function as a global event property, which means you can see the metadata values at the time they were stored for each event. This provides a more accurate view of user activity and allows you to track changes in behavior over time, rather than only seeing the value recorded on the latest event.
Note: For mobile users, historical metadata is supported on versions 2.21.0 and above.
Understand historical metadata
Historical metadata allows you to capture the past values of up to 25 metadata fields, instead of just the current value associated with a visitor or account. This feature gives you the ability to track changes in metadata values over time.
We recommend being selective about which data mapping fields you enable historical metadata for. To best utilize this feature, focus on fields where the values change over time but don't change constantly. As a best practice, consider choosing fields that describe visitors or accounts at a high level, rather than fields that capture temporary or narrowly-scoped assignments, such as project or task IDs. We also recommend keeping track of which metadata fields you enable or disable and when.
To better understand the benefits of historical metadata, consider the overview video and example below.
Imagine you have a visitor in your product named Alice and a metadata field in your subscription related to Account Type with values of Free and Paid.
On Alice's first three visits to the application, she was using a Free plan and visited the "Account Page" on three separate occasions: January 1, January 4, and January 7. After January 7, Alice upgraded her account to a Paid plan and made two more visits to the Account Page in the month of January.
If the Account Type metadata field wasn't enabled as historical during Alice's activity, you would only be able to see the most recent value of her Account Type, which was Paid. All of Alice's previous activity would be associated with Paid as the metadata value since that was the most recently recorded value.
If the Account Type metadata field was enabled as historical during Alice's activity, you could view the unique metadata value for each event at the time it occurred. This means you could see exactly what Alice did in your product when she was on a Free plan and compare it to her activity when she was on a Paid plan.
Tip: When enabling historical metadata, it's important to balance your selection of fields with values that change over time and values that don't change too often. Aim to choose fields that provide high-level descriptions of visitors or accounts, rather than those that capture temporary or narrowly-scoped assignments, like project or task IDs.
Enable historical metadata
If you're an admin user, you can enable historical metadata across all apps in your subscription to function as a global event property. You can't enable historical metadata for:
- Default fields of Visitor ID and Sample Group.
- Metadata with a list, date, time, or undefined data type.
- Segment.com metadata.
You can enable up to a total of 25 data mappings across all levels of data: Visitor, Account, and Parent Account. If you need to enable historical metadata for more than 25 fields, contact your Pendo account representative or Pendo Support.
- Navigate to Settings > Data Mappings in Pendo Engage.
- By default, you're taken to all visitor-level data. If you want to enable account-level data, select the Account Level Data tab.
- In the Metadata table, find the Enable Historical column and select the checkbox next to an event you'd like to enable to function as a global event property.
- Select Enable in the confirmation dialog.
- Repeat Steps 3 and 4 for each metadata field you'd like to enable as historical. You can enable up to 25 fields across all levels of data.
Caution: When enabling historical metadata, there are a few important things to take note of:
- Once you enable historical metadata for a field, it applies to all future events going forward. You can't view historical metadata values for past events.
- You can only enable historical metadata for a specific field three times in a 24-hour period.
- Pendo only shows up to five value changes for non-agent metadata within a rolling 24-hour period. For example, imagine you are tracking a historical metadata value related to a visitor's environment. If a visitor accesses your application in multiple environments and switches between those environments throughout the day, Pendo stops tracking the metadata value after the visitor switches environments for the sixth time that day. Note that this limitation doesn't apply to agent metadata.
To disable historical metadata for a data mapping, deselect the checkbox and select Disable in the confirmation dialog. Once disabled, the metadata still displays with event properties (such as in Data Explorer, the segment rule builder, and the Event Properties tables) so that you can track the values related to when that field was enabled as historical metadata.
Use historical metadata
When using historical metadata, the metadata must be included in the initialize function of your install script. If you have a multi-page app architecture or iFrames, consider verifying that your install script is configured to capture this data each time you initialize Pendo.
To learn about how to view and report on historical metadata, you can watch the below video and refer to our article on Event Properties. Note that the video uses the former name of this feature: promoted metadata.