Best practices when changing the URL for a web application

This article applies to web applications where Pendo is installed through the Pendo install script or the browser extension. If your application's URLs are changing, follow these steps to determine if any changes are needed in your Pendo subscription.

Review installation and the URL change

Before you change your application’s URL, review how Pendo is installed and what exactly is changing in the URL structure.

Confirm Pendo will remain installed

If Pendo is installed through the install script: Confirm with your developers that the Pendo install script remains installed after the URL change. If you're adding Pendo to a new environment, ensure the Pendo install script is added.

If Pendo is installed through the browser extension: 

1. Go to Settings > Subscription settings > Applications and select the specific application.
2. Hover over the Websites row, and select the edit icon. 
3. Add more domains or edit the existing ones as needed.  

Confirm what part of the URL is changing

When looking at the URL structure,  we consider anything between the https:// and the first / to be the domain. Everything after that first / isn't considered the domain.

Here's an example of just the domain being changed:

• Old URL: https://acmecrm.io/dashboards/sales-metrics 
• New URL: https://app.product.io/dashboards/sales-metrics

Here's an example where more than the domain is changed:

• Old URL: https://acmecrm.io/dashboards/sales-metrics
• New URL: https://app.product.io/reports/dashboards/sales-metrics

Confirm if the URL change will impact the user experience

If the URL is the only change and the product experience is identical between the old and new URLs, you should modify existing Page tags and use a single Page tag to track both the old and new URL. If the user experience is also changing, you may want to create new Page tags to track usage separately. This will also be helpful for feature tags and guides that may be only relevant for a specific experience.

Review and update your Page tags

After confirming your installation, review your existing Page tags to ensure they still match the updated URLs.

Export current Page tags

1. Go to Product > Pages.
2. Select Manage columns and add Include Rules and Exclude Rules.
3. Export the table as a CSV.

Evaluate current rules

Review the Include Rules and Exclude Rules columns:

• If a rule starts with //*, the domain is wildcarded and this rule will match a URL with any domain.
• If a rule starts with a domain ( //app.acme.io), this rule will only match a URL with that specific domain.

Update existing Page tags (if the user experience stays the same)

• If only the domain is changing, confirm that the current page rules use wildcarded domains.
• If the rest of the URL is changing, add a new rule to the existing Page tag to match the new URL.

Create new Page tags (if the user experience is different)

1. Leave the original Page tag in place to match the old URL.
2. Create a new Page tag to match the new URL.

For more guidance on Page tagging, see Page tagging and URLs for Page tagging. For assistance with creating or editing Page tags in bulk, contact our support team.

Review guides and Feature tags

If you created new Page tags or changed the user experience, review your guides and Feature tags to make sure they still work as expected.

Guides

• Open each published guide and review if the guide content needs to be updated.
• If the guide step is targeted to a specific Page location, check that the assigned Page tag is still accurate.
• If the guide step is anchored to an element, verify that the configured CSS selector still matches the element.

Features

• Review Feature tags to ensure the CSS selector rules still match to the correct UI elements.
• Update existing feature rules or create new Feature tags if the CSS selectors have changed.

Review related subscription settings

Finally, check your related subscription settings so staging, domain filters, and CNAMEs align with the new URLs.

Staging domains

If you use a staging environment to test guides:

1. Go to Settings > Staging in the top-right corner of the page.
2. Add or update domains as needed.

Exclude and include lists

If you want Pendo to exclude events from non-production environments:

1. Go to Settings > Exclude and include lists in the top-right corner of the page.
2. In the Server Host/Domain section, add or update relevant domains.

CNAME settings (domain changes only)

If CNAME is enabled for the application, you may need to set up a new CNAME record for the new domain, and assign it to the application in Pendo. You can coordinate with our support team to make these changes.