Tech Note: Managing a major application update or UI refresh
If you are in the process of rebuilding an application that already has Pendo installed on it there are a few considerations that you will want to make. Changes in the tech stack you are using for the application, UI changes and URL changes can all have an impact on how Pendo will function in that application. This post covers, at a high level, a few of the items that you should take into consideration.
Using an existing Pendo API Key vs a new Pendo API Key
The first decision you will probably want to make is whether or not you want to continue using the same API key that your current version of the application is using - or if you want to use a new Pendo API key on the new version of the application. Pendo API keys are not tied to a single domain or code base - so either option will work.
Reusing a Pendo API key means that all data from the new version of the application will be in the same bucket of Pendo data as the existing version of the application. This can help with pulling high-level metrics like Monthly Active Users or Time in App that you may want to be represented as a combined metric (across both the old and new versions).
Using a new Pendo API key allows you to have separate buckets of data for the old version of the application and the new version. This can work particularly well if there is a slow rollout of the new version and if users can switch back and forth between the old and new versions. This allows you to more easily get a count of the number of visitors on either version of the app, the relative time on the app between the two, and other high-level metrics split out between both application keys in Pendo.
UI Element Changes
The new version of your application likely involves extensive UI element changes. This usually also means that the new elements will have new classes and IDs. Because feature tagging and guide targeting is based on matching HTML elements like class and ID you will likely need to re-tag the new version of the application to account for those changes.
URL Changes
The new version of your application may also have a new URL structure. If it is just the domain changing (and none of the paths after the domain change) the impact would be minimal as most page tags wildcard the domain by default. If the entire path is changing you will need to retag pages to account for the new URL structure.
Impact on Analytics
If you are reusing the application key from the old version of your application on the new version of your application there are a few things to consider as far as analytics are concerned:
-
High-level metrics: Your top-level metrics like Monthly Active Users, Time in App, and PES score will be combined between the old and new versions of your application. This makes it difficult to split out high-level usage analytics to compare the old and new versions of the application.
-
Feature Tagging: The new UI elements likely use new classes and IDs which means you will need to re-tag those elements. You merge feature tags together to create 1 feature tag that covers both the old and new versions of any specific button. You may also run into collisions where an HTML element in the new version of your application uses the same class or ID as a different element in the old version of your application. Because Pendo offers retroactive analytics this can cause some confusion with past events being picked up by the new tag.
-
Page Tagging: The new version of the application may use an entirely new URL structure. If this is the case re-tagging pages will be necessary. You can merge page tags to create page tags that cover both the old and new URLs for any page in the application. Similar to features though you will want to be careful about collisions - where a URL rule may unintentionally match either an old (or new) URL.
If you are using a new application key for the new version of your application you will avoid these issues by simply re-tagging the pages and features in the new version of the application under the new application key.
Impact on Guides
If you are reusing the API key from the old version of your application on the new version of your application all of the guides you have created under the old application will automatically apply to the new application. Guide display however is largely based on having guide settings match the URL and HTML elements in the guide location settings. Due to the changes listed above it is possible that most guides (tied to specific pages or elements) may no longer activate correctly. In this case you will need to edit the guides (or the underlying page tags) to make the guides work on the new application.
If you are using a new API key none of your existing guides will be automatically available on the new API key (since guides are set up on a per-key basis). You could use our guide clone functionality to clone guides from the old version to the new version and then edit the cloned version to update the location settings for the appropriate page and HTML element.
Conclusion
Any major change to the UI or underlying code structure of your application will likely result in needing to re-tag pages and features as well as possibly rebuild guides. While there are pros and cons to both using the existing API key or using a new API key in most cases using a new API key will result in less confusion and a cleaner migration process.
Comments
Using an existing Pendo API Key vs a new Pendo API Key
The first decision you will probably want to make is whether or not you want to continue using the same API key that your current version of the application is using - or if you want to use a new Pendo API key on the new version of the application. Pendo API keys are not tied to a single domain or code base - so either option will work.
Reusing a Pendo API key means that all data from the new version of the application will be in the same bucket of Pendo data as the existing version of the application. This can help with pulling high-level metrics like Monthly Active Users or Time in App that you may want to be represented as a combined metric (across both the old and new versions).
Using a new Pendo API key allows you to have separate buckets of data for the old version of the application and the new version. This can work particularly well if there is a slow rollout of the new version and if users can switch back and forth between the old and new versions. This allows you to more easily get a count of the number of visitors on either version of the app, the relative time on the app between the two, and other high-level metrics split out between both application keys in Pendo.
UI Element Changes
The new version of your application likely involves extensive UI element changes. This usually also means that the new elements will have new classes and IDs. Because feature tagging and guide targeting is based on matching HTML elements like class and ID you will likely need to re-tag the new version of the application to account for those changes.
URL Changes
The new version of your application may also have a new URL structure. If it is just the domain changing (and none of the paths after the domain change) the impact would be minimal as most page tags wildcard the domain by default. If the entire path is changing you will need to retag pages to account for the new URL structure.
Impact on Analytics
If you are reusing the application key from the old version of your application on the new version of your application there are a few things to consider as far as analytics are concerned:
High-level metrics: Your top-level metrics like Monthly Active Users, Time in App, and PES score will be combined between the old and new versions of your application. This makes it difficult to split out high-level usage analytics to compare the old and new versions of the application.
Feature Tagging: The new UI elements likely use new classes and IDs which means you will need to re-tag those elements. You merge feature tags together to create 1 feature tag that covers both the old and new versions of any specific button. You may also run into collisions where an HTML element in the new version of your application uses the same class or ID as a different element in the old version of your application. Because Pendo offers retroactive analytics this can cause some confusion with past events being picked up by the new tag.
Page Tagging: The new version of the application may use an entirely new URL structure. If this is the case re-tagging pages will be necessary. You can merge page tags to create page tags that cover both the old and new URLs for any page in the application. Similar to features though you will want to be careful about collisions - where a URL rule may unintentionally match either an old (or new) URL.
If you are using a new application key for the new version of your application you will avoid these issues by simply re-tagging the pages and features in the new version of the application under the new application key.
Impact on Guides
If you are reusing the API key from the old version of your application on the new version of your application all of the guides you have created under the old application will automatically apply to the new application. Guide display however is largely based on having guide settings match the URL and HTML elements in the guide location settings. Due to the changes listed above it is possible that most guides (tied to specific pages or elements) may no longer activate correctly. In this case you will need to edit the guides (or the underlying page tags) to make the guides work on the new application.
If you are using a new API key none of your existing guides will be automatically available on the new API key (since guides are set up on a per-key basis). You could use our guide clone functionality to clone guides from the old version to the new version and then edit the cloned version to update the location settings for the appropriate page and HTML element.
Conclusion
Any major change to the UI or underlying code structure of your application will likely result in needing to re-tag pages and features as well as possibly rebuild guides. While there are pros and cons to both using the existing API key or using a new API key in most cases using a new API key will result in less confusion and a cleaner migration process.
Please sign in to leave a comment.