Google Tag Manager

Evolve loads one GTM container and pushes canonical events to its dataLayer. Analytics, Meta, LinkedIn, Pinterest and Google Ads tags live in that container, not in the theme. The package ships a container export with those five platforms wired to the events, so a new site is a matter of importing it and filling in the IDs. How consent and emission behave is on Tracking and consent.

Set up a container

1. Create a GTM container for the site (Web).
2. Import vendor/racerfish/evolve/theme/gtm_container.json under Admin > Import Container, into a new workspace, merge. It brings the tags, triggers and variables for GA4, Meta pixel, LinkedIn Insight, Pinterest and Google Ads.
3. Edit the five platform variables in the GTM UI with the client's IDs: the GA4 measurement ID, the Meta pixel ID, the LinkedIn partner ID (and conversion IDs), the Pinterest tag ID, the Google Ads conversion ID and labels. Delete the tags of platforms the client does not use.
4. Preview the workspace against the staging site with TRACKING_EMIT=true, click through a form submission and check that the tags fire on the events below.
5. Publish the container.
6. Set the container ID on the site: GTM_ID=GTM-XXXXXXX in the .env, or in the panel under Settings > Tracking. The snippet is rendered server-side; no theme rebuild is needed.

The container's tags should keep their consent checks: Evolve sets the Consent Mode default before GTM loads, and the banner updates it.

Where the IDs come from

Platform	Where to find the ID
GA4	Analytics Admin > Data Streams > Web, "Measurement ID" (G-...)
Meta pixel	Events Manager > Data Sources, the pixel's ID
LinkedIn	Campaign Manager > Analyze > Insight Tag, partner ID; conversions under Conversion Tracking
Pinterest	Ads > Conversions > Pinterest Tag, tag ID
Google Ads	Goals > Conversions, each action's conversion ID and label

Events the theme pushes

Every push has an event name and a payload that follows the GA4 recommended events, so GA4 tags can forward them unchanged and the other platforms map them.

Event	Fired by
page_view	every page load
form_submit, form_error	the form component on submit and on validation failure
generate_lead	a successful form submission (also sent server-side)
sign_up	registration flows
view_item, add_to_cart, remove_from_cart, begin_checkout, add_payment_info, add_shipping_info	the shop
purchase	a completed order (also sent server-side)
search	site search
contact interaction and booking completion	click-to-call, mail links, booking flows

Any element can declare its own event with an x-track attribute holding a JSON payload, for example the social icons' outbound clicks. Custom code calls window.gtmTrack(name, params). The exact payload of every event is specified in theme/GTM_CONVERSION_SPECS.md in the package.

Migrating a project from the per-platform adapters

Projects built before 2.6 loaded GA4, the Meta pixel, LinkedIn and Pinterest through theme adapters fed by window.*_TRACKING globals. Those globals still render behind TRACKING_LEGACY_VARIABLES=true. The migration replaces direct SDK calls and x-track payloads with dataLayer pushes, removes the adapter files and the SDK loaders, imports the container and finally turns the flag off. The step-by-step guide is theme/GTM_LEGACY_MIGRATION.md in the package.

Verifying

• Live: the page source contains googletagmanager.com/gtm.js?id=GTM-.... Staging shows it only with TRACKING_EMIT=true.
• In the browser console, google_tag_manager is defined and dataLayer lists the consent default followed by the page events.
• GTM Preview mode (Tag Assistant) connects to the site and shows which tags fired on which event, and the consent state at that moment.
• GA4 DebugView shows the generate_lead once from the browser and once from the server with the same event ID when both paths are on.