Planning your Pendo installation

Pendo captures product usage insights and user poll responses, and engages users in your app to onboard, educate, and guide them to value. This article covers installation planning, selecting the data you need to send with your install script ("snippet") or SDK, and preparing to use Feedback.

Planning your Pendo install helps your team accurately capture all of the visitor and account metadata you need to get an understanding of your users in your product.

We also have developer documentation that provides the details that engineers need to successfully install Pendo on your web or mobile app:

Web Installation Overview and Demonstration – Runtime: 6:24

 

Preparation

To prepare for the installation process, choose what metadata you would like to be associated with visitors and accounts in your app. Talk to your developers about the values that are available. You might find that you need additional development to collect all the metadata you want to use for analytics in Pendo.

Additional metadata can be added after the installation but you should avoid changing the Visitor and Account ID setup in the initial installation. 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 reach out to a Pendo representative to add integrations to your subscription.

Installation process

The process for installing Pendo involves the following:

1. Choose Visitor and Account IDs.
2. Select other metadata you want to attach to your Visitor and Account IDs.
3. Review PII, security, and privacy policies.
4. Send install instructions to your developers.
5. Verify that Pendo is recording your data.
6. Add users and get started.

Step 1. Choose Visitor and Account IDs 

Pendo displays information at the individual level (visitors) and the organization level (accounts). Within Pendo, you can see reports of overall activity and the health of your accounts, and then drill into individual visitors within each account. 

What visitors and accounts are

The visitor is an individual unique user. These are end-users that you can identify based on how they signed up or logged in to your product. A Visitor ID is typically an email or a unique number. Anonymous visitors are also supported with cookies.

A visitor is different from an account, which is a collection of multiple visitors. Accounts are groups that multiple visitors are associated with. 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 the Developer's guide to installing Feedback.

A Visitor ID can have multiple account IDs associated with it. For example, a visitor might have access to multiple organizations in your app. 

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. 

Guidelines for IDs

Before installing Pendo, determine what you will use as your Visitor ID. The Visitor ID is your source of truth for who an end-user is and is how you follow them through their entire product journey. When determining what you will use as a Visitor ID, consider the following:

• Visitor ID values are limited to 128 bytes in size. Larger values are truncated.
• The Visitor ID should match across all Pendo apps, including web and mobile apps.
• Email address is generally the easiest unique Visitor ID available that's recognizable in Pendo and accessible in Pendo reports or CRM products for creating custom segments.
• You can't change the Visitor ID without losing product usage and guide history data for users prior to the date it's changed.

Warning: The Visitor ID value should not be changed after the user has initialized Pendo the first time and generated a visitor record. If the Visitor ID value changes, a new visitor record is created with new product usage history and no guide view history. You retain all your previous analytics with the old Visitor ID but the Visitor record is then recreated with the new Visitor ID with no connection to the previous ID. The visitor will have a new first-login date, see all automatic Guides that target them again, and will restart any onboarding checklists.

All other fields can change as you learn how you want to use Pendo, but the Visitor ID should stay the same. The Account ID also shouldn't change for the most accurate account-level analytics and Feedback usage.

Development and testing

If Pendo is installed in multiple environments (such as dev or staging), and these environments use the ame 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 Development and Testing.

ID Examples

Visitor:
UID with environment specifier - prod-100001
Hashed email address - 2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824
UUID - d6beaf08-c632-11ea-87d0-0242ac130003
Account:
Company name - Acme INC
Account Identifier from CRM - EE669047-E897-E311-A5A7-D89D67633DBC

Step 2. Select other metadata

To get meaningful segmentation and guide targeting with Pendo, you can add other metadata.

What metadata is

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 a user. 

For more information, see Visitor and account metadata.

Guidelines for metadata

We recommend that you send us anything you might use to segment your visitor and account data. Keep other departments in mind too. Even if some data isn't used by the Product team, it might be useful to Customer Success or Marketing teams. Check-in with other departments and find out what their reporting and in-app messaging needs are.

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, most recent role is passed to Pendo. 

Visitor metadata examples

• Unique Visitor ID
• First Name
• Last Name
• Email Address
• User Permissions (ie. admin, user, read-only)
• Role or Title
• Department

Account metadata examples

• Unique Account ID
• Account Name
• Industry (ie. Accounting, Real Estate, Healthcare, Technology, etc.)
• Market Segment (ie. SMB, Mid-market, Enterprise)
• Account Creation Date or Sign Up Date
• Contract Start Date
• Renewal Date
• Plan Price or Contract Value

Step 3. Review PII, security, and privacy policies

Security and privacy are important anytime information is shared with a third party. User data and other identifying information can be highly sensitive. Pendo hosts your application data in a secure multi-tenant environment and gives you full privacy control of your user data. 

Pendo is a custodian of your data. We allow you to view and process your data using our tools or software you integrate with Pendo. We don’t sell or distribute PII or customer data and doing so is prohibited under the California Consumer Privacy Act (CCPA). You control your data and you control who can see it.

Pendo annually completes SOC 2 Type 2 audits covering all five Trust Services Principles: Security, Availability, Processing Integrity, Confidentiality, and Privacy. To date, Pendo’s reports have been issued with no exceptions in related controls. Pendo undergoes third-party penetration testing twice per year.

What PII is

Personally identifiable information (PII) is any data that could be used to identify a specific individual, whether used alone or with other relevant data. Sensitive personal information could include email address, Social Security Number (SSN) or other national ID number, name, mailing address, credit card information, financial information, or medical records.

Guidelines for PII

Many Pendo subscriptions pass additional information such as an email or account name in their instance of Pendo, along with other demographic information to help build out segments, but it isn't required.

If you're uncomfortable sharing PII, Pendo only needs a unique identifier for each user in your application to work effectively. This doesn't require any personally identifiable information for the visitor or the account. It can be a randomly generated value that is anonymous to Pendo.

What Pendo captures

The Pendo platform doesn't collect any user-entered text or information within form fields in your application unless you configure that data collection using Event Properties.

By default, the names of fields, buttons, and other elements within the page are captured with the application data, which makes for easier tracking, but no user-supplied information is included. These page elements can include PII displayed in your application UI. It's possible to disable text capture within the API, but this can limit the analysis that can be performed with your application data.

Pendo collects IP addresses by default. Some customers find this useful for identifying the geographical location of their users. However, some prefer not to capture IP addresses. If you don’t want to capture IP addresses in Pendo, contact Pendo Support to disable IP address tracking for your app.

If you have any concerns about your security while using Pendo, detailed overviews of our security practices are available in the articles linked below or you can reach out to a Pendo representative to discuss your security requirements.

• Security and Privacy
• Data Privacy & Security at Pendo
• General Data Protection Regulation (GDPR)
• Content Security Policy (CSP)

JWT Installation

Pendo exists on the front end of your site. It's possible that a bad actor could send fake metadata to Pendo using your install script to access the Pendo Agent. The risk is low as only your authenticated users could have access to your install script and API key. If there is a security concern, a JSON Web Token (JWT) installation allows our back-end to verify that the metadata sent by the install script hasn't been tampered with.

Most customers use a standard installation without JWT. However, you can install Pendo with JWT. This method requires additional steps for activation, changes to the install script, back-end development, and continuous rotation of tokens to function properly.

JWT snippet installation requires all requests to be signed using your JWT shared secret, otherwise, data is dropped. You can find the shared secret on the Install Settings page, which is only accessible by admins. JWT doesn't have to be set up in the initial install and can be set up later if needed.

If you require JWT installation, find out more in the JWT Installation article or contact a Pendo representative for assistance.

Step 4. Send install instructions to your developers

Although you don’t need to be a developer to use Pendo, it does require a quick technical install. For most web apps, the install script ("snippet") is inserted into your common HTML template without changing more than the metadata. For mobile apps, the Pendo mobile SDK is added to your app code and initialized when you're ready to identify the visitor.

We highly recommend that you communicate with your developers as soon as possible to coordinate your needs so that you have a quick and successful implementation.

Your developers need to install the web snippet into the page header and install initialization into your authentication stack after the user has been authenticated. Both pieces of the install script need to be present on every page that you want to collect data from. Mobile developers add the SDK to your app, initialize Pendo when your app loads, and identify the visitor when you're ready to collect data and display guides.

Step 5. Verify that Pendo is recording your data

After Pendo is installed, it can take up to two hours for data to start feeding into Pendo. You receive an email when we begin receiving data. When you receive this email, go to your Subscription Settings page, accessible by admins, to check the data flowing into the Raw Events tab.

Step 6. Add users and get started

Pendo gives everyone in your organization access to analytics and customer engagement tools, even if they don't know how to code.

Guidelines for inviting users

Invite others to use Pendo as soon as possible to help set up your subscription. User roles help you give access to colleagues so that they can contribute whilst also protecting your subscription settings.

The following people can benefit from having access to Pendo:

• Product can use Pendo to get the insights they need to deliver products that users love.
• Design can use Pendo to help design guide templates and themes for content creators.
• Front-end Engineers can use Pendo to help tag Features and Pages.
• Customer Success or Support can use Pendo analytics to find patterns in user behavior.
• Marketing can use Pendo to develop in-app engagement strategies or set up NPS polls.
• Professional Services can use Pendo to build onboarding Guides.
• Cross-functional Content Creators can use Pendo to build guides for all of their internal or external in-app engagement campaigns.

Add users

To add users to your subscription:

1. Navigate to Settings > Users in the left-side navigation. 
2. Select + Add User in the top-right of the page.
3. Enter the user's details and choose their permissions.
4. Select Add User in the bottom-right corner of the page.

For more information, see the Roles and Permissions Overview.

Get started

Once Pendo is installed, you have access Pendo's data visualization, engagement, and adoption tools. We recommend starting in each of the following areas to build a foundation for your Pendo subscription that will give you room to grow as you use Pendo to learn about your users, drive adoption, and build the products they love.

• Review your subscription settings and change your time zone.
• Add new Users.
• Review your Visitor and Account data mappings.
• Tag Pages and Features to use analytics and product usage segmentation.
• Create Segments of your visitors and accounts.
• Create Guides to engage your users.
• Create a Resource Center to give your users access to your guides, announcements, and onboarding checklists.

Pendo Performance

Pendo’s Javascript files are hosted and served on Amazon’s Cloudfront CDN utilizing state-of-the-art edge caching. The Javascript file is minified and compressed to approximately 100KB and loads asynchronously.

Data is securely transmitted through TLS from each user’s browser to our server every two minutes and when a page is unloaded. Data is compressed prior to sending and each transmission is less than 2KB.

For additional information, see the Security & Privacy article.

Advanced Installation

There are some scenarios where you might need help with your installation. A Pendo representative can talk through your concerns and assist with your installation.

You might need direct support with your installation if you have any of these requirements.

• Non-standard web snippet installations
• Security concerns
• Custom integrations
• Segment.io or Google Tag Manager installations
• API integrations or webhooks

Frequently Asked Questions

Where do I install the install script ("snippet")?

Everywhere. The Pendo needs to be installed on every page. If your app uses iframes, install within each iframe.

Why do universally unique IDs matter?

These IDs identify each visitor and account. If any of these are duplicated, multiple users’ data are aggregated under a single ID, skewing your analytics and reducing your ability to target guides effectively.

Visit the Pendo Academy for a video on avoiding and resolving ID collisions. If you're on our US domain, visit the US Pendo Academy. If you're on our EU domain, visit the EU Pendo Academy. 

Why does metadata matter?

Metadata allows you to create powerful segments that yield rich insights and target your guides. You can segment visitors and accounts based on any information that's passed to Pendo. For more information, see Visitor and Account Metadata.

Who are your unknown users?

Unknown or anonymous users are those who don’t sign in to your app. You can enable analytics on your unknown users and allow them to see guides in Subscription Settings.

How do I hide data that I don't want to see?

Pendo can hide data based on Server/Host Domain, IP Address, Visitor ID, or Account ID using include and exclude lists. For more information, see Exclude and Include Listing.

Can I host the agent locally?

The install script pulls in pendo.js, which contains the Pendo agent code. pendo.js can be downloaded and hosted by your application if you don't want it to be pulled from Pendo’s CDN. For instructions on hosting the agent reference Self-hosting the Pendo Agent.

Can Pendo be installed on-premise?

The Pendo agent can be hosted locally and included in on-premise applications. Pendo currently only hosts and processes data in the cloud, so this still requires a connection to the internet and Pendo servers must be added to Include Lists. For more information, see Exclude and Include Listing. Broadly, guides are inbound traffic and analytics are outbound.