When updating to a newer version of UTAG, it is important to do thorough testing to ensure that changes made progressively throughout the different versions do not alter the tags firing or the data being sent with the tags. Ideally, once UTAG is updated to a newer version, the tags and the data sent with the tags should remain identical to the previous UTAG version. If the profile's version of UTAG is being updated, follow the steps below to ensure the profile retains its integrity.

In This Article:

Steps For Updating UTAG

1. Determine the Current Version

Before updating, it's important to know which version of UTAG is currently running on the website as a starting point. If you have the Universal Tag Debugger tool, run it on your site and note the version number at the top right of the tool.

To retrieve the utag.js version from the browser console:

  1. Right click anywhere on the page and select "Inspect" from the menu. This will open the Developer Tools.
  2. Click on the Console tab to display the console.
  3. Type "utag.cfg.v" into the console and press "Enter" or "Return"
  4. The console will display the version (ex: ut4.46.202010262218). The first two sets of numbers are the UTAG version (4.46).

2. Review the Release Notes

Based on the current UTAG version running on the website, there may be many changes that have occurred between that version and the latest version. It's always a good idea to read through all of the changes before updating your version. The release notes can be accessed here.

3. Synchronize Publish Environments

Since the changes made to the UTAG version are global (it is a profile template, which means the changes are implemented regardless of version publish or environment), it is recommended to ensure that all publish environments are identical before updating. That way the QA process only needs to occur once and will cover all environments.

4. Save a Backup

We recommend creating a local copy of the UTAG version template before updating to the latest version. Should any issues occur, it makes it easier to roll back to the previous version.

5. Update the Tag Template

Follow the instructions to update your UTAG Loader template .

6. Verify Tags/Extensions/Load Rules

Once the version is updated and published to a test environment, it is recommended to thoroughly test all load rules, tags, and extensions to ensure they match how they were sent in the previous version. Refer to the charts below for items to review when verifying the profile.

7. Validate with Vendors

Review the data coming into each vendor's platform to ensure that it matches the data that was collected with the previous version. If the data seems off, it could be that an extension or mapping was affected by the update and needs to be corrected.

Validating Changes by Version

When validating a UTAG update, it's recommended to initially publish the update to a testing environment (DEV/QA) to preserve the original setup in PROD. The two versions can then be tested side by side to ensure that the tags and network requests align between versions, along with any data sent with tags.

Version 4.40 up to 4.45

Profile Settings If S2S was being used, note that support was removed completely. (Removed legacy s2s support, as this was previously removed from Tealium iQ)
Tags If "Privacy Manager" is being used, check tags to ensure they are firing as expected based on cookie settings. (The OPTOUTMULTI cookie is re-checked with each call to utag.view() and utag.link().Tags triggered directly by UID also checks the OPTOUTMULTI cookie settings before firing)

Version 4.26 up to 4.39

Review the chart above AND

Load Rules
  • If "meta" values were used in load rules, they could change with each "view" event instead of staying static, which could affect how the load rules evaluate.

  • If "utag_main" cookie values are used in load rules, ensure the load rules still evaluate properly after the update, as values may have changed (Fixed a bug that incorrectly decodes any instance of $ value in the utag_main cookie and render it as a separator instead. Following this fix, the utag_main cookie values are not ‘double decoded’ anymore.)

  • If _t_visitor_id and _t_session_id are used in load rules, they will need to be updated to use the new variables (ut.visitor_id and ut.session_id), as the original variables no longer exist. An extension can also be used to update the old variables with the new variable's values.
Tags
  • If "meta" values are used in tag mappings, review tag data as they could change with each "view" event instead of staying static, which could affect the data sent by the tag.

  • If _t_visitor_id and _t_session_id are used in tag mappings, they will need to be updated to use the new variables (ut.visitor_id and ut.session_id), as the original variables no longer exist. An extension can also be used to update the old variables with the new variable's values.

  • If the "Privacy Manager" extension is being used, changes to the OPTOUTMULTI cookie could prevent tags from firing that were previously firing for utag.view() events.

  • Review manual utag.link() calls to ensure they are not triggering new tags that weren't previously triggered, as utag.link() calls now load tags that were not previously loaded on the page.

  • Review mappings for "utag_main" cookie values to ensure they are intact after the update as this could affect tag data (Fixed a bug that incorrectly decodes any instance of $ value in the "utag_main" cookie and render it as a separator instead. Following this fix, the "utag_main" cookie values are not ‘double decoded’ anymore.)

  • Review ALL tag data to ensure it is passing correctly with the tag since the utag.link() / utag.view() data is no longer merged into the utag.data object. If the merge is needed, it can be set using an extension. (The utag.js 4.40 template takes advantage of a publish engine update so that the merge is no longer required. In version 4.40, the utag.data global object is not updated with each utag.link() or utag.view() call.)

  • If "JS Page" variables are used in mappings, review tag data to ensure it matches as before (JS Page vars are now updated to their current value with every utag.view() or utag.link() call).

  • Verify that all iframe type tags are executing as expected (If an iframe with the same ID already exists, the iframe is not added again. Instead, the iframe src is updated.)
Extensions
  • If "meta" values are used in extensions or load conditions, they could change with each "view" event instead of staying static, which could affect the data returned by the extensions or how the extensions are triggered.

  • If _t_visitor_id and _t_session_id are used in extensions or extension load conditions, they will need to be updated to use the new variables (ut.visitor_id and ut.session_id), as the original variables no longer exist. An extension can also be used to update the old variables with the new variable's values.

  • If blocking tags are present in the profile, review any "all tags" scoped extensions to ensure data loss has not occurred due to executing AFTER the completion of blocking tags.

  • Review extensions set to "All Tags" to ensure they are scoped correctly (should be scoped to "All Tags After Load Rules" since the other two "all tags" options were not available in previous versions).

  • If "utag_main" cookie values are used in load conditions or extension code, ensure the load conditions still evaluate properly after the update and that the values are correct, as the values may have changed (Fixed a bug that incorrectly decodes any instance of "$" value in the "utag_main" cookie and render it as a separator instead. Following this fix, the "utag_main" cookie values are not ‘double decoded’ anymore.)

Version 4.25 and Below

Review BOTH charts above AND

Load Rules
  • If query string parameters or meta tag values are used in load rules, evaluate the load rules to ensure they evaluate properly. Values are no longer lowercased, so "exact" values may no longer be "exact". An extension can also be set to use the utag.cfg.lowermeta override to set the flag to true, enabling lower-casing for meta tags. (This only applies to the name of the name/value pair for that meta tag.)

  • Verify that all load rules evaluate as they did previously since ALL page data is now available in utag.view() and utag.link() calls. This could cause load rules to evaluate as "true" that previously evaluated as "false", due to the presence of different variables. Make sure events aren't double-firing due to multiple events. (Previously, utag.view and utag.link calls only knew about the data you passed them. Items like b["qp.campaign"] were not available. Now, all “built-in” data points such as URL, meta, or cookie values are added to the data layer for the utag.link() and utag.view() calls. Also, dynamic items that may have changed for AJAX sites (such as b["dom.url"]) are re-built so they use the current value.)
Tags
  • Verify tags are not over-firing, as load rules are now evaluated for ALL utag.view() and utag.link() calls.

  • If query string parameters or meta tag values are used in tag mappings, evaluate the tag data as values are no longer lowercased. An extension can also be set to use the utag.cfg.lowermeta override to set the flag to true, enabling lower-casing for meta tags. (This only applies to the name of the name/value pair for that meta tag.)

  • If custom scripts sources are used in any tag, these will now become blocking resources. It may make sense to transition these tags to use a Tealium Generic Tag to avoid blocking resources. (When you enter the location for the custom script source advanced setting for a tag, this tag automatically becomes a blocking tag. This tag still loads asynchronously, but subsequent asynchronous scripts. For example, utag.10.js does not load until the blocking tag is complete.)

  • Review the "wait flag" configuration to ensure they match how tags loaded before the update (Previously, tags executed in the order specified in Tealium iQ. These tags then waited for tags placed higher in the order to load before loading themselves. This means that you may now have a mixture of tags with their Wait Flag set to ‘No’ and tags with their Wait Flag set to ‘Yes’ in the same profile.)

  • Review manual utag.view() calls, as they may be triggering new tags that weren't previously loaded, since load rules are now re-evaluated for each "view" call. (This feature is enabled by default in utag.js 4.26. Disable this feature to keep current behavior. See utag.cfg.load_rules_ajax flag details for more information.)

  • Make sure events aren't double-firing due to multiple events being triggered on the SAME page, since ALL page data is now available in utag.view() and utag.link() calls. This could cause load rules/conditions to evaluate as "true" that previously evaluated as "false", due to the presence of different variables. (Previously, utag.view and utag.link calls only knew about the data you passed them. Items like b["qp.campaign"] were not available. Now, all “built-in” data points such as URL, meta, or cookie values are added to the data layer for the utag.link() and utag.view() calls. Also, dynamic items that may have changed for AJAX sites (such as b["dom.url"]) are re-built so they use the current value.)
Extensions
  • If query string parameters or meta tag values are used in load conditions or extensions, evaluate the load conditions to ensure they evaluate properly. Values are no longer lowercased, so "exact" values may no longer be "exact". An extension can also be set to use the utag.cfg.lowermeta override to set the flag to true, enabling lower-casing for meta tags. (This only applies to the name of the name/value pair for that meta tag.)

  • If utag.data or utag_data objects are being modified in extensions, note that these modifications can affect the base data layer (utag_data) since the utag_data object now becomes a reference to the utag.data object. Changing one object changes the other. Make sure data is sending as it did before the update.
Version history
Revision #:
4 of 4
Last update:
3 weeks ago
Updated by: