Google Tag Manager migration
Freshpaint can migrate your GTM tags using an automated script.
Overview
When migrating more than just one or two Google Tag Manager (GTM) tags to the Freshpaint GTM Template, the process can be error-prone and time-consuming.
To help with this, Freshpaint offers a migration script which automates the process. Currently, Freshpaint must run this script on your behalf, after you’ve invited us with access to your GTM account. Please contact support@freshpaint.io for further details.
Migrating Tags
Freshpaint currently supports migrating from native GTM tags to the following Freshpaint Destinations, using the Freshpaint GTM Template:
Google Analytics 4 (Proxy)
Google Ads
Google Ads Call Conversions (migrates to the freshpaint.registerCallConversion sdk call, not to a destination track call)
Facebook Conversions API (from Gallery template or Custom HTML)
Bing Ads
Twitter Ads
StackAdapt conversion (from Custom HTML)
theTradeDesk conversion via static tracking tag (from Custom HTML)
Using the Freshpaint GTM Template and the Google Tag Manager Destination at the same time is not currently supported.
When Freshpaint runs the migration, the changes will be written to a GTM Workspace of your choosing.
The changes will not be “Live” in the GTM Workspace until you submit them for publishing.
The target GTM Workspace will typically be the “Default Workspace” present on any GTM Container.
If you want to be able to keep the Freshpaint migration output in a Workspace separate from the Default Workspace used for your ongoing maintenance work, you can create a separate GTM Workspace for migration test purposes, such as “Freshpaint migration”.
Other Migration Features and Options
When Freshpaint runs the migration, in addition to migrating tags for the above destinations, it will:
Create a GTM Variable called "Freshpaint Environment ID", referenced by all Freshpaint tags
Ensure the Freshpaint destinations for the migrated tags are created - if a given Destination already existed, then the non-sensitive config parameter is checked (the non-sensitive config paramter is automatically set if the destination is created by the migration). A note specific to Facebook Conversions API: The Access Token must be set by you, post-migration.
Report any not-yet-Allowlisted event properties encountered in the migrated tags
There is also an option to have the migration configure GTM for the Freshpaint snippet (as an alternative to including it in your page source). Here's how this works:
A "Freshpaint Snippet" (or other name you specify) Custom HTML tag is created for the Freshpaint snippet, referencing the "Freshpaint Environment ID" GTM Variable, triggered on All Pages: Page View
Any Freshpaint tags which are triggered on a Pageview are configured with a Setup Tag, specifying the "Freshpaint Snippet" tag.
Going forward, when you create new Freshpaint tags which are triggered on a Pageview, you must add this SetUp Tag to ensure reliable delivery to Freshpaint.
Finally, the following filtering options are available to include or exclude sets of tags from being migrated:
Include or Exclude by GTM Folder(s)
Include Paused Tags
Include only specific Destinations
GA4 Notes
If you have GA4 event tags which are conversions, you'll need to manually add event property conversion with a value of true either to the GA4-event tag pre-migration or the Freshpaint-GA4-event tag post-migration:
Validating
Use GTM Preview Mode to try out the migrated changes in the target Workspace before they are published as the "Live" version. In this mode, when you run your site in the Preview window, it will use the tags in the Workspace, not the “Live” version. The GTM Tag Assistant browser tab allows you to inspect what Tags are firing, the Tag Parameter values being sent, Variables, the Data Layer, and Errors (if any).
For each tag, perform the action that fires that tag, confirm the event comes through the Freshpaint Live View, and confirm the event shows up in the destination.
Publishing
When you’re comfortable that the migrated changes are correct, you can Submit them for publishing as the “Live” version.
If you're submitting from a Freshpaint-specific GTM workspace such as "Freshpaint migration", be sure to sync any pending changes in the GTM Default Workspace to what was just published.
If for any reason you need to go back to your previous “Live” version, you can quickly do so via the GTM UI, by clicking ‘Set as Latest Version”, from the GTM "Versions" tab.
Last updated
