Tech Note: Transform the URL collected by Pendo using Location API (web only)

Developer documentation for the location API is available in the Agent API documentation. Your developers must implement the location API in your application.

Overview 

The Location API provides a method for modifying the browser URL that the Pendo agent receives from your application. The actual application is still using the original browser URL, and end users only see the browser URL, but the agent receives a more detailed or sanitized version of the URL that is used in analytics and guide targeting.

The Pendo agent collects and stores the browser URL in each event. This URL is used by Pendo to match page tags to events in page and feature tagging, and show guides on specific pages. There are some situations where the browser URL is not usable and you need to transform the URL sent to Pendo.

• The product is a single page application, and the URL does not change as a user navigates to different parts of the product.
• There is a particular part of the product that you want Pendo to understand as distinct pages, but the URL does not change.
• The URL contains sensitive or extraneous information which should not be sent to Pendo
• The URL changes as the user scrolls down a page (hashed URLs), which causes a guide to continuously redisplay and present a poor user experience.
• The current URL is difficult or impossible to tag as desired with existing page rule functionality.  Modifying the URL sent to Pendo would make page tagging easier. 

Implementing the Location API does require development resources. Please also review the Location API section in our official developer documentation for full API documentation :   Agent API documentation.

Requirements/Limitations

• Agent 2.108.0 or greater for web applications
• Agent 2.126.0 or greater for Electron applications
• Not supported for Pendo Launcher (Chrome and Edge extensions) installations
• Preview functionality does not support Location API. Learn more here. 

Location API Functionality

Location API transformation is available during initialization or programmatically via the API at any time. You have the ability to alter how the URL is represented when it’s recognized by the Pendo agent whenever you need to. 

Reminder: For full documentation on each Location API function, please visit:  Agent API documentation.

Ignore the browser URL completely

Use the setUrl function to tell the Pendo agent what the URL should be. The result must be a valid URL. The Pendo agent will stop detecting the browser URL and will only recognize the URL defined by setUrl. Call the setUrl function again to rewrite the URL with a new URL as needed.

Use the function useBrowserUrl to stop using the URL provided by setUrl. UseBrowerUrl pulls the current browser URL and resumes normal agent functionality.

This is recommended for situations where most of the time (or all of the time) the browser URL will not be relevant for Pendo. 

Transform the browser URL

Use the addTransforms function to modify the browser URL so that the Pendo agent only collects the transformed URL. Any part of the URL can be transformed, including:

• query string parameter
• hash
• pathname
• hostname
• href

Use the clearTransforms function to clear any existing Transforms previously created for the URL. 

This is recommended for all other situations where the browser URL needs to be transformed for Pendo. 

Validate the result of Location API

Use the getHref function to see the transformed URL. This can be useful when validating the results of your implementation. 

Examples for common scenarios

• Remove sensitive data in the URL
• Add parameters to the URL
• Limit which parameters are captured
• Drop hashed URL fragments

Remove sensitive data in the URL 

It is possible to remove sensitive data that is included in the URL path in a customer’s application before the URL is collected by Pendo and stored in raw event data. When implemented, the Location API transform is applied to every read of the URL just like any other transform during initialization or programmatically via the API. This prevents Pendo from seeing the sensitive data at every point. 

• Original URL: https://app.acme.com/user/123-sensitivedata-123/details
• After Location API: https://app.acme.com/user/details

Add parameters to the URL 

In some situations, a single-page app or hashed URL cannot provide different URL paths for different app pages. So that Pendo can distinguish between the different app pages, additional parameters can be added to the URL. Location API can transform the URL during initialization or programmatically using defined variable statements.

• Original URL: https://app.acme.com/
• After Location API: https://app.acme.com?page=dashboard

Limit which parameters are captured 

In some situations, you may need to limit the parameters in a query string captured by the Pendo agent to approved parameters only. Location API can search the URL and only capture the specified query parameters in the raw event. This can be done during initialization or programmatically via the API.

• Original URL: https://app.acme.com/marketing?utm_medium=social&source=facebook&lang=fr&search=crm
• After Location API: https://app.acme.com/marketing?lang=fr&search=crm

Drop Hashed URL fragments 

You may want to drop hashed URL fragments from events collected by the Pendo agent especially if those fragments do not provide meaningful context for page analytics. 

On the other hand, your application might use hashes to provide direct links to a specific portion of the page. Since Pendo guides reload every time the URL changes, this may result in guides continuously reloading as the user scrolls down the page and those hashes change. 

To resolve both situations, location API can clear URL fragments after a hash during initialization or programmatically via the API.

• Original URL: https://app.acme.com/dashboard/documentation#widget
• After Location API: https://app.acme.com/dashboard/documentation

Replacing legacy methods with the Location API

Important:  This section is only relevant if you are already using a legacy method  to customize the URL and wish to start using Location API. If you have never customized the URL before and are planning to do so for the first time, please disregard this section addressing legacy methods.

Prior to the release of Location API, Pendo had several other methods for customizing the URL. However,  those methods were complex and could not be used in combination. Those methods are now considered deprecated. They will not be removed from the code, but their use is discouraged and the location API will not function properly if these methods run concurrently. 

Deprecated methods for customizing the URL :

• sanitizeUrl
• annotateUrl
• ignoreHashRouting
• queryStringWhitelist
• xhrWhitelist

If any of the above legacy methods are used, the location API will not be available. Any location configuration used or API calls made will be processed but not applied.

sanitizeUrl 

SanitizeURL was used to remove sensitive data that was included in the URL path in a customer’s application before the URL was collected by Pendo and stored in raw event data. SanitizeUrl was only applied when URLs were sent to Pendo and not when detecting if a URL had changed.  Location API accomplishes a similar outcome as SanitizeUrl and is applied to every read of the URL just like any other transform during initialization or programmatically via the API.

annotateUrl 

AnnotateURL was used to write parameters to the URL when a single-page app or hashed URL couldn’t provide different URL paths for different app pages. This method was called very frequently when the agent was attempting to detect URL changes and could be challenging to implement with enough granularity.  Location API can accomplish the same outcome. 

ignoreHashRouting

IgnoreHashRouting was used to drop hashed URL fragments from raw events collected by the Pendo agent when these fragments did not provide meaningful context for page analytics. Location API can accomplish the same outcome.

queryStringWhitelist 

QueryStringWhitelist was used to limit the parameters in a query string captured by the Pendo agent to approved parameters only.  Location API can accomplish the same outcome.

xhrWhitelist 

xhrWhitelist was only used if the configuration option xhrTimings was also enabled. It was similar to queryStringWhitelist and was used to control which query parameters were captured by the Pendo agent. The difference was,  xhrWhitelist would remove any query string parameters that were NOT in the list. Location API can accomplish the same outcome.