Use Location API to customize the URL collected by Pendo

This article explains when to use the Location API to customize the URL collected by Pendo. The Location API provides a consistent method for transforming the URL when the default application URL isn’t sufficient for your use case. Location API is supported for web apps when Pendo is installed via the install script. It is not supported for browser extension installations or mobile app installations.

Example Use Cases

Technical Requirements and Details

• Agent 2.108.0 or greater for web applications 
• Agent 2.126.0 or greater for Electron applications

Location API is not supported for browser extension installations or mobile app installations.

Implementing the Location API requires an Engineering resource. Location API transformation is available during initialization or programmatically via the API at any time. Learn more here: Developer Documentation—Location API.

Location API only transforms the URL being collected by the Pendo agent, which Pendo uses for reporting and guide display. No changes are made to the application URL or the URL that your end-users see. You can use Location API to transform all of the URLs across your application or just the URLs for specific pages. 

Please note Location API transformation is not retroactive. Historical events previously captured by Pendo will retain their original URLs and will not be modified. 

Pendo has some legacy methods for customizing the URL that are now considered deprecated: sanitizeUrl, annotateUrl, ignoreHashRouting, queryStringWhitelist, and xhrWhitelist. If you are using any of these legacy methods, Location API will not work. We strongly recommend replacing them with Location API instead.

Implementation Best Practices

1. Decide how the application URLs need to be transformed and make a detailed plan.
   
   For example, if your product’s URL never changes, you will need Pendo to collect unique URLs as the user navigates through your product. Identify the different pages you want to tag in Pendo and consider what URL structure would make it easier for you to create page rules. Decide which parts of the URL you want to modify and what text you want to add, edit, or remove.
   
   
2. Ask an Engineering resource to make the necessary code changes to your application. Share this documentation with them: Developer Documentation- Location API.

Verify the Implementation

Once Location API is successfully implemented, there are a few ways to check that Pendo is collecting the transformed URL. All four methods are valid, and you can choose the one that you are most comfortable with. 

• View the transformed URL when tagging pages via the Visual Design Studio
• View the transformed URL using the Pendo Debugger
• View the transformed URL in the Developer Console using the function pendo.location.getHref()
• View the transformed URL in the Developer Console using the function pendo.validateEnvironment()
  
  

Use the Visual Design Studio

This method requires access to the Pendo subscription. Within Pendo, go to Product > Pages, launch the Visual Design Studio and go to a page on your application where Location API has been implemented.

In the ‘Current URL’ box, you’ll see the URL that the Pendo agent is collecting. If Location API was implemented successfully, this URL should be different from what you see at the top of your browser window. You can then follow the normal process for page tagging.

Use the Pendo Debugger

Launch the Pendo Debugger and go to a page on your application where Location API has been implemented. To launch the Debugger, you can either follow the steps in this article or use the function pendo.enableDebugging() in the Developer Console.  

Once the Pendo Debugger is open, click on the Config tab and scroll down to the Frame Selector section. Look for the rows ‘Frame href’ and ‘Browser URL’:

• ‘Frame href’ shows the URL that Pendo is collecting. 
• ‘Browser URL’ shows the URL that appears in your browser. This is not being collected by Pendo and is only being displayed for comparison purposes. 

If Location API is implemented successfully, these two rows should have different values. 

(Optional: If your page has multiple iFrames, you’ll be able to choose a specific iFrame from the Frame Selector dropdown)

Use pendo.location.getHref() in the Developer Console

Go to a page on your application where Location API has been implemented. Open the Developer Console for your browser (instructions for Chrome).  Type in pendo.location.getHref() and hit enter. The result will be the URL that the Pendo agent is collecting. If Location API was implemented successfully, this URL should be different from what you see at the top of your browser window.

Use pendo.validateEnvironment() in the Developer Console

Go to a page on your application where Location API has been implemented. Open the Developer Console for your browser (instructions for Chrome). Type in pendo.validateEnvironment() and hit enter. Scroll down to the ‘URL Validation’ section.

If Location API was implemented successfully, you’ll see a note that says “URL has been customized...” and the transformed URL will also be displayed.