The Google Tag Manager auto-migration tool made migrating to GTM V2 a breeze, and was the recommended method for migrating. However, your automatically migrated Containers have a few telltale remnants of GTM v1. I recommend you follow the steps below to replace these vestiges with their functionally equivalent GTM V2 counterparts. These changes won't alter the way Containers function on the front-end, but will:
- Give Containers a cleaner configuration
- Allow Containers to take full advantage of V2 features
- Support consistency across Containers
Once you complete the steps below, the only clue that your Container was created in GTM v1 will be a line in the Container change history:
- List of User-Defined Variables only contains actual user-defined Variables.
- Variable field dropdowns are shorter and more relevant.
- Container has a safeguard against modification of core Variables.
In GTM V2, the 16 default v1 Macros have been replaced by Built-In Variables. Nomenclature aside, the difference is that the Built-In Variables in V2 are immutable, whereas in v1, they were merely defaults that could be renamed, have their logic modified, or deleted. And automatic migration brings all Macros into GTM V2 as custom Variables. Each of these (as long as it's default logic was not modified) has a built-in equivalent.
- First, make sure all the Built-In Variables are deactivated. (At least the 'Event' Built-In Variable and the Built-Ins from the 'Pages', 'Clicks', 'Forms', and 'History' groups).
Note: If you have already started using a Built-In Variable since migrating, you won't be able to deactivate it. In that case, try to delete the equivalent migrated v1 Macro. If you can, great. Otherwise, wherever the Built-In Variable is referenced, change it to reference the equivalent migrated v1 Macro (e.g.
), then deactivate the Built-In Variable.
- Change the name of each migrated v1 default Macro to the name of the Built-In Variable it should be replaced with. For reference, here are all the old Macro names mapped to their replacement Built-In Variable names:
Default Macro name (v1) Built-In Variable name (V2) element Click Element Form Element element classes Click Classes Form Classes element id Click ID Form ID element target Click Target Form Target element text Click Text Form Text element url Click URL Form URL event Event history change source History Source history new state New History State history new url fragment New History Fragment history old state Old History State history old url fragment Old History Fragment referrer Referrer url Page URL url hostname * Page Hostname url path Page Path
* Before replacing 'url hostname', check it's 'Strip www' setting. By default, this setting is unchecked (exhibiting the same behavior as the Built-In Variable 'Page Hostname'). If 'Strip www' is checked, then do not replace this User-Defined Variable with the Built-In without checking every reference throughout the Container.
- Activate the replacement Built-In Variables, choosing "Overwrite Existing" when the 'Naming Conflict' dialog pops up.
Note: There are six default Macros that actually have two equivalent Built-In Variables. The migrated '
element *' Macros have both '
Form *' and '
Click *' counterparts, and can be replaced with either. But even though they are functionally identical, replacing the generically-named '
element *' Macros with more specifically-named Variables could result in some confusing references to those Variables. (Which may be the only reason why replacing default Macros was not handled by the automatic migration.) So, replace these with the Variable that would usually make sense in your Container, then update any confusing references in Tags, Triggers, and other Variables.
- No unnecessary listener Tags in your Tags list.
- Simpler Edit Trigger screens, as internal event names will be hidden behind the shiny new UI.
One of the big changes in GTM V2 is that event listeners are activated implicitly by Triggers, and listener Tags are no longer necessary. For migrated Containers to take advantage of this change, you need to change each 'Custom Event' Trigger that has a condition like `
equals gtm.*` and update it to use the new Trigger event UI. Then, simply delete the listener Tags.
For an in-depth look at setting up Triggers using the new UI, check out Simo Ahava's walkthrough.
This last post-migration task takes advantage of the new built-in 'All Pages' Tag firing condition. This is so minor that choice of whether or not to implement this is largely inconsequential. But it is a remnant of v1, and it's quick and easy to change, so for the sake of being comprehensive I've included it here.
Note: If you've modified the default 'All Pages' v1 Rule to only fire under certain conditions, then it is not redundant and you should not follow these steps.
For each Tag that fires everywhere:
- Open the Tag.
- Under 'Fire On', click the 'x' on the 'All Pages' Trigger to deselect it.
- Select the first condition "All Pages" (this condition has the same name as the Trigger deselected in the previous step, but notice it's a different color).
- Save Tag.
After you've done this for all Tags, you can delete the 'All Pages' Trigger.
Now that you're up to speed on where Google Tag Manager auto-migration falls short, and the steps you have to take to ensure it goes smoothly, share your questions/comments below. Don't forget to subscriber to our newsletter for more GTM goodness to come.