Visitor and account metadata are collected under Visitor and Account IDs. Visitor and Account IDs are how you describe and label your users. Visitors represent individual users of your application, and accounts represent groups of visitors, typically the company they belong to.
This article describes how to supply metadata at the visitor and account levels to enrich your analytics and your options for guide targeting. You can leverage this metadata when you build segments and reports, and you can add and remove metadata over time.
Send us metadata
Before installing Pendo, identify what information and metadata you want to capture. Add any variables to your Pendo install script under the Visitor and Account sections. For guidance, see the Developer's guide to installing Pendo.
We recommend you send us anything you would find beneficial in segmenting your visitor and account base. Several examples include role, account status, account manager, contract expiration date, account creation date, and so on.
Unlike Visitor and Account IDs, you can change metadata fields. Examples of visitor-level metadata include: first name, last name, email address, user permissions, and role or title. Examples of account-level metadata include: account name, industry, market segment, account creation date, signup date, contract start date, renewal date, and contract value.
Supported key values
Supported syntax for metadata values includes letters, numbers, and underscores (_).
A custom value or "key" must start with a letter or an underscore. No other types of syntax are supported for the starting character. For example, if you have a key such as "300", you need to change it to "_300" to work properly with Pendo. If this syntax isn't followed, you can't create segments or run reports using those custom fields.
Custom language metadata
The default language metadata field in Pendo is collected from the visitor's browser settings by the agent. Custom visitor metadata can be passed through by the agent or integrations, like Salesforce. Custom language metadata fields must use a name other than language since this name is reserved for browser language metadata and can't be replaced.
You can specify a different metadata field in your localization settings through Settings > Subscription Settings > Localization Settings. To learn more, see Localization.
Map your metadata
Your metadata is configured in Data Mappings, which has a separate tab for Visitor Level Data and Account Level Data (and Parent Account Metadata if enabled). This is where Admin users can specify the type of data fields that are sent to Pendo. For more information, see Data Mapping and Data Types in Pendo.
View your metadata
Visitor and account metadata are different for every Pendo customer because not everyone sends the same metadata fields. Admin users can check the metadata being sent to Pendo in Settings > Data Mappings. The Data Mappings page is where you can see the names and types of data Pendo uses for analytics.
If you're not an Admin user, you can instead go to http://app.pendo.io/metadata. The first dropdown menu lists all the metadata currently sent to Pendo. Selecting an item from the dropdown shows you metrics, such as how many unique values are being sent for that metadata field.
Understand metadata groups
Visitor-level and account-level data have the following metadata groups associated with them.
Agent metadata
This is metadata from your product that's passed through the install script, commonly referred to as "the snippet". You can't modify these fields manually or through the API—you can only change them within the code. The agent data must be reviewed inside of Pendo to ensure that the data type listed in Pendo matches the actual data type sent in the install script.
This metadata automatically updates when a user visits a page in your application and passes the fields to Pendo. If an agent metadata field is incorrectly populated, it can only be updated the next time the user visits your application and passes the correct information.
Several metadata fields are provided out of the box:
Default account metadata
- First Visit
- Last Visit
- Number of Days Active
- Number of Events
- Number of Visitors
- Time on Site
Default visitor metadata
- First Visit
- Last Visit
- Number of Days Active
- Number of Events
- Time on Site
- Most recent browser version and name
- Most recent operating system
- Most recent server name
Salesforce metadata
These metadata fields are pulled in from Salesforce through our integration and aren't editable from the Data Mappings page. This is only an option if the Salesforce integration is enabled. For more information, see Salesforce integration with Pendo Engage.
HubSpot metadata
These metadata fields are pulled in from HubSpot through our integration and aren't editable from the Data Mappings page. This is only an option if the HubSpot integration is enabled. For more information, see HubSpot integration.
Segment metadata
These metadata fields are pulled in from the Segment.com integration and aren't editable from the Data Mappings page. This is only an option if the Segment.com integration is enabled. For more information, see Segment.com integration overview.
Custom metadata
Use custom ("Pendo only") metadata fields if the data you want to add doesn’t fall into any of the above groups. You can add custom fields on the Data Mappings page. These must link to a visitor or account. To do this, open the details of an individual visitor or account and add a value.
Update this field manually on a specific Visitor Details or Account Details page, or update in bulk through our API to add larger amounts to custom fields.
Format metadata correctly
When adding any new type of metadata (agent, custom, Salesforce, HubSpot, or Segment) that's a date, Pendo uses the ISO8601 W3C (for example, 2006-01-02T15:04:05.999-05:00) format. Ensure you’re using this format before sending data into Pendo.
If you want to use a different date format, other formats are supported. For a list of supported date formats, see the Engage API documentation. Contact Technical Support to change your date format.
Metadata field names must start with a letter or an underscore and can include any combination of letters, numbers, and underscores. Field names containing spaces or other unsupported characters won't be created in Pendo.
For more information on supported data formats, see Data mapping and data types in Pendo.
Enable historical metadata (beta)
Visitor and account metadata always show the details associated with the last recorded event for a user. If you want to have historical context around user metadata, you can choose to enable historical metadata for up to five data mapping fields in your subscription.
When you enable historical metadata, it's considered a global event property, as it allows that data to function like an event property by capturing the value on every event at the time it occurred.
Notice: You can't enable historical metadata for default values of Visitor ID and Sample Group, metadata with a list type, and Segment.com metadata.
To learn more, see Historical metadata (beta).
Audit your metadata
As your app and user base evolve over time, it's important to regularly audit your metadata. When you encounter the need to remove duplicate fields or gain insight into overall metadata field usage, the following resources can help you make informed decisions:
- Use our Metadata page to understand which fields are used by your visitors and accounts.
- See our linked API documentation to learn which segments, guides, and reports are using a particular metadata field or to obtain a list of where all metadata fields are in use.
Delete agent or custom metadata
Admin users can delete agent or custom metadata through the Data Mappings page. To delete a metadata field, hover over the field, select Remove, and then confirm the deletion. The confirmation prompt displays for a few seconds to prevent accidental deletions. If no confirmation occurs, the button reverts to the Remove state.
Once you confirm, the metadata field is removed from the list and is no longer available for use in segmentation.
Note: If you delete an Agent type field from the Pendo UI, but don't delete it from your install script, Pendo continues capturing the data but won't re-populate into the UI. To undo the deletion, contact Technical Support.