Location API

The Pendo Location API provides a comprehensive and consistent way to update or change the URLs that are passed to Pendo from your application so that the desired active URL is correctly and safely recorded in raw events collected by the Pendo agent. The location API can be used either declaratively when pendo.initialize is invoked or dynamically using the programmatic API.

Requirements

• 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

Common Use Cases

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

Available Methods

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. There are several functions available for rewriting the URL entirely and controlling this behavior.

pendo.location.addTransforms()

This function accepts an array of Transform objects. The Transform object must contain three fields:

• attr is a String that is the attribute of the affected URL.
• action is a String that is the type of effect.
• data is any static value or a function that returns a static value to be used as the content to make the change.

Attribute	Actions Available
search	AllowOnlyKeys - This removes any other query string parameters. data provides an array of key names to allow. ExcludeKeys - This removes the specified query string parameters. data provides an array of key names to exclude. AddTo - This adds the provided query string parameters. data can either provide an array of key names or an object of key/value pairs to add. Replace - This removes the current querystring and replaces it with whatever is provided. Clear - This removes the current querystring.
hash	Replace - This replaces the current hash value with what is provided. Clear - This removes the current hash.
pathname	Replace - This replaces the current pathname with what is provided.
hostname	Replace - This replaces the current hostname with what is provided.
href	Replace - This replaces the current HREF with what is provided.
protocol	ForceSecure - This forces the protocol to https.

// Example
pendo.location.addTransforms([{
    'attr': 'pathname',
    'action': 'Replace',
    'data': 'pen/do'
}, {
    'attr': 'search',
    'action': 'ExcludeKeys',
    'data': function(hostname, url) {
        return ['key1', 'key2'];
    }
}]);

// Can also be set in initialize statement
pendo.initalize({
    ...,
    location: {
        transforms: [
            {
                'attr': 'hash',
                'action': 'Clear'
            }, {
                'attr': 'search',
                'action': 'AddTo',
                'data': function() {
                    return {
                        'key1': 'value1',
                        'key2': 123,
                        'key3': false
                    };
                }
            }, {
                'attr': 'protocol',
                'action': 'ForceSecure'
            }
        ]
    }
});

pendo.location.clearTransforms()

This function takes no arguments and clears any existing Transforms previously created for the URL.

pendo.location.setUrl()

The setUrl function allows you to define the URL detected by the Pendo agent. The Pendo agent stops detecting the browser URL and only recognizes the URL defined by setUrl until useBrowerUrl is called.To change the URL, call the setUrl function with the desired URL. Call the setUrl function again to rewrite the URL with a new URL as needed.

This function takes the argument representing the desired URL and uses that instead of the value retrieved from the browser. The result must be a valid URL. AddTransforms are applied to this URL, just as they are when the URL originates from the browser.

Using setUrl disconnects the agent from the browser’s URL and prevents the agent from detecting URL changes in the browser. To keep functionality consistent, a 0.5 second poll is used to check the value of setUrl for changes.

// Fixed browser URL, API controlled url
pendo.location.setUrl('http://app.funco.com/current/page');

pendo.location.setUrl(function () {
    return determinePageUrl(); // implement your own function for this
});

// also can do this when initializing
pendo.initialize({
    ...,
    location: {
        setUrl: function () { return determinePageUrl(); } // or static string or URL
    }
});

pendo.location.useBrowserUrl()

This function removes any URLs provided by the setUrl function. The agent resumes using the URL provided by the browser.

pendo.location.getHref()

This function returns the current HREF as determined by the location API that is used for all URL purposes by the Pendo agent.