Choose IDs and metadata

Last updated:

Before installing Pendo, identify what information you want to capture. Pendo displays information at the individual level (visitors) and the organization level (accounts). To get meaningful segmentation and guide targeting with Pendo, you can add other metadata through the install script. Metadata is useful for segmentation and reporting in Pendo. For example, you can use metadata to deliver guides based on user role and to report on customers by account manager.

Add any variables to your Pendo install script under the Visitor and Account sections. For guidance, see the Developer's guide to implementing Pendo using the install script.

Visitor and Account IDs

Visitor and Account IDs are how you describe and label your users. There are many areas of Pendo where Visitor and Account IDs are the readable names in analytics and reports. You can also upload a CSV of Visitor and Account IDs to create a custom segment. 

Visitors represent individual end users of your application that you can identify based on how they signed up or signed in to your product, and accounts represent groups of visitors, typically the company they belong to. A Visitor ID can also have multiple Account IDs associated with it. For example, a visitor might have access to multiple organizations in your app. 

A Visitor ID is typically an email or a unique number. Anonymous visitors are also supported with cookies. Visitor IDs for anonymous end users are in the following format: VISITOR-UNIQUE-ID.

An Account ID is typically a business name or a unique number. Account IDs are required if you use Pendo Feedback. For more information, see Configure for Feedback.

Warning: After you've set your Visitor and Account IDs, they shouldn't be changed. All other fields can change as you learn how you want to use Pendo, but the Visitor and Account IDs should stay the same.

ID changes

ID values shouldn't be changed after a visitor or account record has been created. If the ID value changes, a new record is created for that visitor or account with new product usage history and no guide view history. You retain all your previous analytics with the old ID but the visitor or account record is then recreated with the new ID and no connection to the previous ID. This results in a new first-sign-in date for the visitor, which redelivers all automatic guides that target them and restarts any onboarding checklists for that visitor.

You might be able to work with Pendo Support to merge IDs if there is a one-to-one mapping between the old and new IDs. This merges all product usage history and guide view history under the new IDs. For more information, see Data deletion and manipulation services.

IDs in development and testing

If Pendo is installed in multiple environments (such as dev or staging), and these environments use the same Visitor and Account IDs, product usage and guide activity is aggregated for all environments when looking at analytics. Certain datasets can be removed using the Exclude and Include Lists or by adding a prefix or suffix to the Visitor ID in those environments and excluding them from a segment. For more information, see Pendo in multiple environments for development and testing.

Metadata

Most apps collect additional information about their visitors and accounts to better understand who is using the product. All of that data can be used for better analytics and engagement in Pendo. This is metadata.

Metadata is stored at the account and visitor levels. Visitor and account metadata shows the details associated with the last recorded event for an end user. 

Unlike Visitor and Account IDs, you can change metadata fields. While metadata is tied to the Visitor or Account ID, unlike Visitor and Account IDs, metadata can be updated at any time. You can add new fields or change values to apply to the history of a Visitor or Account ID.

Metadata can also be pulled into Pendo using our integrations with other platforms. Many of these integrations are codeless and can be set up after the initial installation. For more information, read about our Integrations partners or contact a Pendo representative to add integrations to your subscription.

Visitor metadata examples

  • First name (highly recommended)
  • Last name (highly recommended)
  • Email address (highly recommended)
  • User permissions (for example, admin, user, read-only)
  • Role or title
  • Department
  • Paid or trial user

Account metadata examples

  • Account name (highly recommended)
  • Paying status (highly recommended)
  • Account value (such as ARR or MRR, also used in Feedback reports)
  • Business tier
  • Industry (for example, Accounting, Real Estate, Healthcare, Technology)
  • Market segment (SMB, Mid-market, Enterprise)
  • Account creation date or sign-up date
  • Contract start date
  • Renewal date
  • Plan price
  • Account manager or CSM
  • Location

Visitor ID guidelines

Before installing Pendo, determine what to use as your Visitor ID. Pendo relies on Visitor IDs to make the end-user record unique. The Visitor ID is your source of truth for who an end-user is. This is how you follow a visitor through their entire product journey.

Email addresses make good unique Visitor IDs. This is what we use as Visitor IDs at Pendo. You can also pass visitor email addresses as metadata. This is useful for custom segmentation, reporting, and communicating with your users.

When determining what to use as a Visitor ID, consider the following:

  • Visitor IDs should be globally unique. A Visitor ID must represent only one person through their entire customer journey, matching across all Pendo apps in a subscription, including web and mobile apps.
  • Visitor IDs should be recognizable and match your business tools. Email addresses are the most straightforward Visitor IDs to read and understand.
  • Visitor ID values are limited to 128 bytes in size. Larger values are truncated.
  • Don't use \ or " in a Visitor ID. These characters can result in errors in Pendo.
  • You can't change the Visitor ID without losing product usage and guide history data for users prior to the date it's changed.

Account ID guidelines

We highly recommend using Account IDs, which are necessary for account-level analytics and reports, and for using Pendo Feedback. For more information on data requirements for Feedback, see the Configure for Feedback.

Even if you’re not a Feedback customer, we recommend using account information associated with a group of visitors, including a universally unique Account ID across environments and product lines, to optimize the user experience of Pendo.

At Pendo, we use subscription name as your Account ID. We recommend the following for Account IDs:

  • Account IDs should be globally unique. An Account ID must represent only one account across all Pendo apps, including web and mobile apps.
  • Account IDs should be recognizable to identify a group of visitors across apps and environments, for example, AcmeCRM.
  • Don't use \ or " in an Account ID. These characters can result in errors in Pendo.
  • Don't change Account IDs after you've initialized Pendo for the first time. Changing Account IDs identifies new accounts using new data, breaking continuity with previous Account IDs.

Metadata guidelines

We recommend that you send us anything you might use to segment your visitor and account data. Keep other departments in mind too. 

  • Check with other departments and find out what their reporting and in-app messaging needs are. Even if some data isn't used by the Product team, it might be useful to Customer Success or Marketing teams. 
  • We strongly recommend using email metadata. Email metadata is accessible in Pendo reports, can be used to create custom segments, and can be used to email users who voted for a feature in Pendo Feedback.
  • 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 aren't created in Pendo.

You can add additional metadata after install. Additional metadata automatically updates the visitor and account details when a user activates Pendo in your app and passes the values during initialization. In visitor and account details, these additional attributes reflect the most recent value. For example, if a visitor's role changes, the most recent role is passed to Pendo. 

Note: If you're uncomfortable sharing PII, Pendo only needs a unique identifier for each user in your application to work effectively. This can be a randomly generated value that is anonymous to Pendo.

Was this article helpful?
2 out of 2 found this helpful