> For the complete documentation index, see [llms.txt](https://addressable.gitbook.io/knowledge-base/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://addressable.gitbook.io/knowledge-base/event-tracking/addressable-pixel/pixel-via-google-tag-manager-gtm/google-tag-manager-template-migration-guide.md). # Google Tag Manager Template - Migration Guide This guide covers how to upgrade from the previous Addressable Pixel template (v1) to the new version in Google Tag Manager. The process typically takes 10–15 minutes. {% hint style="info" %} For the full setup guide for the new template, see [Pixel via Google Tag Manager (GTM)](https://addressable.gitbook.io/knowledge-base/event-tracking/addressable-pixel/pixel-via-google-tag-manager-gtm). For the previous version's documentation, see [Legacy (v1)](https://addressable.gitbook.io/knowledge-base/event-tracking/addressable-pixel/pixel-via-google-tag-manager-gtm/legacy-v1). {% endhint %} ## Before You Start ### When did it change The template was released and updated on **Apr 15th, 2026**. If you installed the template prior, you will need to do this migration, otherwise you can skip to the [proper docs](/knowledge-base/event-tracking/addressable-pixel/pixel-via-google-tag-manager-gtm.md). ### What changed The new template replaces the old **Standard/Custom** event selector with three **Tracking Modes**: * **PageView** — Same as before, tracks page views and automatic wallet connects * **Event Tracking** — Suggested events (Registration, Wallet Connect, Purchase, FTD, Deposit) and custom events with built-in revenue fields * **User Properties** — New capability for enriching user profiles (User ID, wallet, email, social handles) ### What to expect When you accept the template update in GTM: * The template fields update to the new version * Existing tags will show the new fields, but previous values (event name, conversion checkbox, object properties) will be cleared * You will need to reconfigure each tag Your **Pixel ID**, **triggers**, and **historical data in Addressable** are not affected. ## Migration Steps {% stepper %} {% step %} #### Document your existing tags Open GTM and go to **Tags**. Most setups have 2–5 Addressable Pixel tags. For each one, record the following: * **Tag name** in GTM * **Standard** or **Custom** under Event Name * **Event name** (e.g. PageView, Lead, Purchase, Subscribe, or a custom name) * Whether **Mark as conversion event** was checked * Any **Object Properties** (name/value pairs) * The **Trigger** assigned to the tag A screenshot of each tag works fine. {% endstep %} {% step %} #### Map your old tags to the new template Use the table below to understand how your existing configuration maps to the new template:
Old Template (v1)New Template
Standard → PageView→Tracking Mode: PageView (default)
Standard → Lead→Tracking Mode: Event Tracking → Custom → Event Name: "Lead"
Standard → Purchase→Tracking Mode: Event Tracking → Suggested Events → Purchase
Standard → Subscribe→Tracking Mode: Event Tracking → Custom → Event Name: "Subscribe"
Custom → (any name)→Tracking Mode: Event Tracking → Custom → Event Name: (same name)
Custom → with conversion checked→Tracking Mode: Event Tracking → Custom → (same name) + check Mark as conversion event
Custom → with Object Properties for revenue→Tracking Mode: Event Tracking → Suggested Events → Purchase, FTD, or Deposit (with built-in revenue fields)
No equivalent→Tracking Mode: User Properties (new capability)
{% hint style="info" %} If you were previously using Object Properties to send revenue data (transaction ID, amount, etc.), switch to the **Suggested Events** revenue types in the new template. The fields are now built in — no need to manually type property names. {% endhint %} {% endstep %} {% step %} #### Accept the template update {% hint style="warning" %} **Do not publish after this step.** Accept the update, then reconfigure your tags in Step 4 before publishing. Publishing before reconfiguring will cause your live tags to send events without the correct configuration. {% endhint %} Follow These Steps: * Log into [**Google Tag Manager**](https://tagmanager.google.com/) * Select the correct **Account/Container** * You should see a notification bar at the top indicating a template update is available — click **View** * Click on the **Addressable Pixel** entry * Review the changes, then click **Accept update** If you don't see the update notification, go to **Templates** on the left sidebar, find **Addressable Pixel** under Tag Templates, click on it, and check for an update prompt. {% endstep %} {% step %} #### Reconfigure each tag Using your notes from Step 1 and the mapping from Step 2, update each tag: * Go to **Tags** on the left sidebar * Click on the tag to edit it * Your **Pixel ID** should still be populated * Set the correct **Tracking Mode** and fill in the fields according to the mapping table * Verify the **Trigger** is still correctly assigned * Click **Save** Alternatively, you can delete the old tags and create new ones from scratch using the [setup guide](https://addressable.gitbook.io/knowledge-base/event-tracking/addressable-pixel/pixel-via-google-tag-manager-gtm). The result is the same. {% endstep %} {% step %} #### Test and publish Once all tags are reconfigured: * Use GTM's **Preview mode** to verify each tag fires correctly * Go back to **Overview** on the left sidebar * Click **Submit** on the top right (blue button) * Give the release a clear name, such as `Migrated to Addressable Pixel v2` * Click **Publish** on the top right (blue button) {% endstep %} {% step %} #### Validate in Addressable After publishing, verify events are flowing correctly: * Log into **Addressable** and click **Data Sources** * Click **View Events** under Addressable Pixel * Go to the [**Raw Events**](https://app.addressable.io/data-sources/addressable-pixel/raw) tab * Confirm your events are showing up with the correct names and properties {% hint style="success" %} Once validated, your migration is complete. Please allow up to 24 hours for events to fully populate in the dashboard. {% endhint %} {% endstep %} {% endstepper %} ## Common Questions
Will I lose historical data? No. Historical event data in Addressable is not affected. The template change only affects how future events are sent.
Can I use the old and new template at the same time? No. GTM allows one version of a community template per workspace. Accepting the update applies to all tags using the template.
I already accepted the update without documenting my tags. Your tags still exist — they just have empty configurations. Go to GTM's **Version History** (under Admin) to view previous published versions and see what your tags looked like before the update.
Do I need to change my Pixel ID? No. Your Pixel ID stays the same. The new template validates the format more strictly (32-character hex string), but existing valid IDs are unaffected.
I was sending revenue data using Object Properties. Use the new **Suggested Events** revenue types (Purchase, FTD, Deposit, or Custom Revenue Tracking). The template now has dedicated fields for Transaction ID, Amount, Chain ID, Token Contract Address, and Exchange Rate. See the [Revenue Tracking section](https://addressable.gitbook.io/knowledge-base/event-tracking/addressable-pixel/pixel-via-google-tag-manager-gtm#setting-up-revenue-tracking) in the setup guide.
--- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://addressable.gitbook.io/knowledge-base/event-tracking/addressable-pixel/pixel-via-google-tag-manager-gtm/google-tag-manager-template-migration-guide.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.