Use the Location API to customize collected URLs

Use the Location API to transform the URL collected by the Pendo Web SDK. This is useful when the default application URL doesn't reflect how your app is structured or when you want more control over the URL collected by Pendo. The Location API works only in web and Electron applications where Pendo is installed via the install script.

Important: Location API isn't supported for browser extension installations or mobile app installations.

Requirements

Before continuing with these guidelines, confirm the following:

• Your web SDK version is 2.108.0 or above for web applications.
• Your web SDK version is 2.126.0 or above for Electron applications.
• You have a developer ready to implement Location API.
• If you're using any of the following deprecated methods, they must be removed before Location API is implemented: sanitizeUrl, annotateUrl, ignoreHashRouting, queryStringWhitelist, and xhrWhitelist. These methods aren't compatible with Location API and will prevent it from working correctly. If you’re not using any of these methods, no action is needed.

How it works

Location API transforms the URL collected by the Pendo Web SDK. This affects how Pendo tags Pages and decides when to display a guide, but doesn't change the actual URL shown to end users. You can use Location API to transform all of the URLs across your application or just the URLs for specific pages. Location API changes aren't retroactive - previously collected URLs remain unchanged.

Plan and implement your transformation

Before implementing the Location API, identify how URLs should be structured for easier tagging and reporting:

• Determine which parts of the URL to keep, edit, or remove.
• Decide how to structure URLs for consistent Page rules.
• Create a transformation plan and share it with your developer.

For example, if your app uses a single-page layout with query parameters, you might want to replace or flatten those parameters into path segments.

Ask your developer to make the necessary code changes to your application. Refer them to the Location API technical documentation. They can implement the transformation:

• During initialization with the Pendo Web SDK.
• Programmatically at any time using the Location API.

Example use cases

Verify your implementation

After implementation, use any of the following methods to confirm that URLs are being transformed correctly.

In the Visual Design Studio

1. Go to Product > Pages in Pendo.
2. Launch the Visual Design Studio.
3. Navigate to a Page where the Location API is active.

4. Check the Current URL field. This should show the transformed URL.

   

In the Pendo debugger

1. Navigate to a Page where the Location API is active.
2. Open the Developer Console and run pendo.enableDebugging() to launch the Pendo Debugger.
3. In the Debugger, go to the Config tab.
4. Under Frame Selector, compare the values for Frame href (Pendo's collected URL) and Browser URL (your browser's actual URL). The two should differ if the transformation was successful.

Tip: If your page has multiple iFrames, you can choose a specific iFrame from the Frame Selector dropdown).

With pendo.location.getHref()

1. Open your browser's developer console.
2. Run pendo.location.getHref()

3. The returned value should reflect the transformed URL.

   

With pendo.validateEnvironment()

1. Open your browser's developer console.
2. Run pendo.validateEnvironment()
3. Scroll to the URL Validation section.

4. Look for the message: "URL has been customized..."