Planning your Pendo Installation

Overview

Pendo captures product usage insights, 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 snippet or SDK, and preparing to use Feedback. Planning your Pendo install will help your team accurately capture all of the visitor and account metadata you'll need to get a complete understanding of your users in your product.

As you go through this article we recommend you fill out the Pendo Installation Workbook to share with your developers. We also have developer documentation that will provide the details engineers need to successfully install Pendo on your web or mobile app.

Web Installation Overview and Demonstration - Runtime: 6:24

 

 

Installation Process

1. Pick visitor and account IDs
2. Select other metadata you want to attach to your visitor and account IDs
3. Review PII, Security, and Performance
4. Send install instructions to your developers
5. Verify Pendo is recording your data

 

First, you need to select the metadata associated with visitors and accounts in your app. Talk to your developers about the values that are available. You may 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 setup after the initial installation. Learn more about our integration partners or reach out to a Pendo representative to add integrations to your subscription.

Although you don’t need to be a developer to use Pendo, it does require a quick technical install. For most web apps, the 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 and have a quick and successful implementation. Your developers will 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 need to be present on every page where you want to collect data. Mobile developers will 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.

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

 

Pick Visitor and Account IDs 

Pendo displays information at the individual level, visitors, and the organization level, accounts.

The visitor is an individual unique user. These are users you can identify based on how they signed up or logged in to your product. A visitor ID is typically email or a unique number. This is different from an account, which is a collection of multiple visitors. Anonymous visitors are also supported with cookies.

Accounts are the groups multiple visitors are associated with. An account ID is typically a business name or a unique number. A visitor ID can have multiple account IDs associated with it, for example if a visitor has access to multiple organizations in your app. Within Pendo, you will be able to see reports of overall activity and the health of your accounts, and then drill into individual visitors within each account. Account IDs are required if you use Pendo Feedback.

Before installing Pendo, determine what you will use as your visitor ID. This is crucial as the visitor ID will be your source of truth for who a visitor is and how you will follow them for their entire product journey. The visitor ID should also match across all Pendo apps, including web and mobile apps. All other fields can change as you learn how you want to use Pendo, but the visitor ID cannot be changed without losing product usage and guide history data for user's prior to the date it's changed. The account ID should should not change for the most accurate account-level analytics and Feedback usage.

There are many areas of Pendo where visitor and account IDs are the readable name in analytics and reports. You can also upload a CSV of visitor or account IDs to create a custom segment. Email address is generally the easiest unique visitor ID available that will be recognizable in Pendo and accessible in Pendo reports or CRM products for creating custom segments.

Note: If Pendo is installed in multiple environments (like dev or staging) and they all use the same visitor ID and account ID, product usage and guide activity will be 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. Learn more about Pendo in Development and Testing.

 

Some 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

 

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 will be created with new product usage history and no guide view history. You will retain all your previous analytics with the old visitor ID but the visitor record will be recreated with the new visitor ID and no connection to the previous ID. They will have a new first login date, they will see all automatic Guides that target them again, and they will restart any onboarding checklists.

 

Selecting Other Metadata

You'll probably need more than just visitor and account ID to get meaningful segmentation and guide targeting. Most apps collect additional information about their users and accounts to better understand who is using the product. All of that data can be used for better analytics and engagement in Pendo.

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 product, it might be critical for customer success or marketing teams. Check in with other departments and find out what their reporting and in-app messaging needs are.

Additional metadata does not have to be set up during install. Raw events in Pendo only store the visitor and account ID with the details of the event. Additional metadata automatically updates the visitor and account details when a user triggers Pendo in your app and passes the values during initialization. In visitor and account details, these additional attributes will reflect the most recent value. For example, if a user’s role changes, it will show the most recent role passed to Pendo. Learn more about metadata.

Examples of Visitor Metadata

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

Examples of Account Metadata

• 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

PII and Security

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.

Personally identifiable information (PII) is any data that when used alone or with other relevant data could be used to identify a specific individual. 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.

If you're not comfortable sharing PII, Pendo only needs a unique identifier for each user in your application to work effectively. This does not require any personally identifiable information for the visitor or the account. It can be a randomly generated value which is anonymous to Pendo. 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's not required.

The Pendo platform does not 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 may include PII displayed in your application UI. It is possible to disable all text capture within the API but it may limit the analysis that can be performed with your application data.

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

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.

If you have any additional 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.

More information on Security and Privacy Settings

More information on Pendo’s Security and Privacy Program

More information on General Data Protection Regulation (GDPR)

More information on Content Security Policy

 

JWT Installation

It is possible to install the Pendo snippet with JSON Web Token (JWT). Most customers use a standard installation without JWT. This method requires additional steps for activation, changes to the snippet, back-end development, and continuous rotation of tokens to function properly.

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 snippet to access the Pendo Agent. The risk is low as only your authenticated users could have access to your snippet and API key. If there is a security concern, a JWT Installation will allow our back-end to verify that the metadata sent by the snippet hasn't been tampered with.

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

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

 

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, check out the Security & Privacy article.

 

Next Steps After Install

Pendo gives everyone in your organization access to analytics and customer engagement tools, even if they don't know how to code. Invite other users to use Pendo as soon as possible to help setup your subscription. User roles will help you give new users the access they need to contribute while protecting your subscription settings.

Who Should Help You Get Started?

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

Add users from the Users page in Settings.

 

Where Should You Focus?

Once Pendo is installed, you have access Pendo's data visualization, engagement, and adoption tools. It can be tough to know what to do first. We recommend starting in each of these areas to build a solid 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

 

Advanced Installation

There are complicated scenarios where you may need help with your installation. A Pendo representative will be glad to talk through your concerns and assist with your installation.

You may 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

 

Install FAQ

Where do I install the snippet?

Everywhere! The snippet 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 will be aggregated under a single ID.

 

Why does metadata matter?

Metadata allows you to create powerful Segments that yield rich insights and personalize guides. You will be able to segment visitors and accounts based on any information that is passed to Pendo. 

Learn more about Metadata.

 

Who are your unknown users?

Unknown or anonymous users are those who don’t login to your app. Do you have anonymous visitors and would you like to see their data? Would you like them to be able to see guides? You can enable analytics on your unknown users and allow them to see guides if you choose in Subscription Settings.

 

Is there data you 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.

Learn more about Exclude and Include Listing. 

 

Can I host the Agent locally?

The installation snippet pulls in pendo.js which contains the Pendo agent code. pendo.js can be downloaded and hosted by your application if you do not 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 will still require a connection to the internet and Pendo servers must be added to Include Lists. Broadly, guides are inbound traffic and analytics are outbound.