• Installing the Magento 2 Google Analytics 4 with GTM Support
• Set up cron
• Uninstalling the Magento 2 Google Analytics 4 with GTM Support
• Extension Compatibility
• Introducing to Magento 2 Google Analytics 4 with GTM Support
• Extension Overview
• Key Features
• Using Magento 2 Google Analytics 4 with GTM Support
• Extension Configuration

Installing the Magento 2 Google Analytics 4 GTM Support extension

Command Line Installation

1. Backup your web directory and store database

2. Download the Facebook Pixel installation package

3. Upload contents of the Facebook Pixel installation package to your store root directory

4. In SSH console of your server navigate to your store root folder:

cd path_to_the_store_root_folder

Run the following command: 

php bin/magento module:enable Aheadworks_GA4

then:

php bin/magento setup:upgrade

after:

php bin/magento setup:static-content:deploy -f

5. Flush store cache; log out from the backend and log in again

Composer Installation

If you are installing an extension from Aheadworks for the first time, you need to add our composer repository to your Magento store:

   1. Login to your ssh console and navigate to your store folder:

cd path_to_the_store_root_folder

Run the following commands:

After the command was executed successfully, you can use the composer to install the extension.

To install the extension:

   2. Login to your ssh console and navigate to your store folder:

cd path_to_the_store_root_folder

   3. Run the following command to install the latest version of the extension:

composer require aheadworks/module-ga4

if you need to install a specific version, run this command:

composer require aheadworks/module-ga4<version>

When prompted, enter Public Key (Username) and Private Key (Password):

Both Public Key (Username) and Private Key (Password) can be found in My Projects and Licenses in your personal account on our site:

 To upgrade the extension: 

To update or upgrade an extension:

Download the updated extension file. Take note of the module-name and version. Export the contents to your Magento root.

If a composer package exists for the extension, run one of the following.

Update per module name:

composer update aheadworks/module-ga4

Updater per version:

composer require aheadworks/module-ga4:<version>

Run the following commands to upgrade, deploy, and clean the cache.

php bin/magento setup:upgrade --keep-generated
php bin/magento setup:static-content:deploy
php bin/magento cache:clean

Set up cron

If you have already configured cron jobs for your Magento installation then you can skip this step. Read the following instructions on setting cron job for your Magento store: Magento user guide.-

Generally, it would be enough to run in SSH console of your server: 

crontab -e

And insert the following line:  

*/3 * * * * php -c <ini-file-path> <your Magento install dir>/bin/magento cron:run
*/3 * * * * php -c <ini-file-path> <your Magento install dir>/update/cron.php
*/3 * * * * php -c <ini-file-path> <your Magento install dir>/bin/magento setup:cron:run

Remember to confirm the Save request when exiting the installation.

Uninstalling the Magento 2 Google Analytics 4 With GTM Support extension

Since Magento introduced declarative Database you need to be very careful when uninstalling or disabling the module.

Manual Removal

1. Disable the module by executing the following commands:

php bin/magento module:disable Aheadworks_GA4
php bin/magento setup:upgrade

2. Remove the extension files from the following folder:

app/code/Aheadworks/GA4

Automatic Removal (via Composer)

1. Disable the module by executing the following commands:

php bin/magento module:uninstall Aheadworks_GA4

Extension Compatibility

Introducing to Magento 2 Google Analytics 4 with GTM Support

Extension Overview

Turn your store’s data into a powerful growth driver with the Google Analytics 4 with GTM Support for Magento 2 extension. This module automates your entire analytics setup and connects your store directly to Google Analytics and Google Ads, ensuring that every purchase, cart update, and product view is captured without gaps. By feeding Google highly accurate data, you eliminate expensive guesswork and train its algorithms to find your highest-value customers.

The extension utilizes secure server-side tracking to bypass ad-blockers and privacy filters, recovering critical conversion data that standard browser pixels miss. It transmits pre-configured data layers directly to your GTM workspace, allowing you to build highly profitable remarketing lists and maximize your return on ad spend (ROAS). Manage your entire tracking configuration straight from your Magento admin area without writing a single line of code.

Key Features

• Set up your entire analytics tracking in minutes using a ready-to-import workspace file;

• Prevent tracking data loss from ad-blockers with reliable server-side data transmission;

• Boost your ad attribution and ROAS by securely sending encrypted customer details to Google;

• Track customer groups, stock status, and custom product attributes directly inside your reports;

• Keep revenue metrics accurate by automatically filtering out free orders and test transactions;

• Test and verify all tracking events on the frontend before launching them live.

Using Magento 2 Google Analytics 4 with GTM Support

Extension Configuration

To configure the global settings for the module, navigate to Stores > Settings > Configuration > AHEADWORKS EXTENSIONS > Google Analytics with GTM.

Connection & API Settings

• Enable GA4 – enables or disables all data collection and extension tracking processes for Google Analytics 4 when set to Yes/No;

• GTM Account ID – alphanumeric input field for the numerical identifier found within the Google Tag Manager Account Settings or workspace URL (e.g., 6332175440);

• GTM Container ID – alphanumeric input field for the specific container numerical tracking identifier (e.g., 239660500);

• GTM Public ID – alphanumeric input field for the public identifier displayed in the GTM interface header (formatted as GTM-XXXXXX), utilized for internal JSON data layer generation. For details on locating this ID, see Google Tag Manager Help: Find your container ID;

• GA4 Measurement ID – alphanumeric input field for the Google Analytics 4 data stream identifier (formatted as G–123456789) embedded into the generated GTM tracking assets. Learn how to find this in Google Analytics Help: Find your Measurement ID;

• Enable Measurement Protocol Tracking – enables or disables server-side event monitoring and offline conversion tracking via direct transmission to Google Analytics servers when set to Yes/No;

• API Secret (appears only when Enable Measurement Protocol Tracking is set to "Yes") — enter the secret key generated in your GA4 Data Stream settings to authorize server-to-server requests. This key ensures secure server-side event tracking, such as offline orders or refunds. For step-by-step instructions on generating this token, refer to Google Analytics Developers: Measurement Protocol API secrets;

• Google Tag Manager Head Snippet (JS) (appears only when Enable Measurement Protocol Tracking is set to Yes)  – text area field to paste the primary GTM JavaScript snippet, which is injected automatically at the highest possible position within the HTML <head> tag of all storefront pages (the payload must include the opening <script> and closing </script> HTML tags);

• Google Tag Manager Body Snippet (Noscript) – text area field to paste the secondary GTM <noscript> tracking snippet, which is injected automatically immediately after the opening HTML <body> tag on all storefront pages;

• Generate Retrigger File – button that compiles and generates a dedicated JSON tracking configuration file based on the specified GTM and GA4 identification data for workspace import operations. Import this file directly into your Google Tag Manager container to automatically configure or update all required variables, triggers, and tags. Review the detailed walkthrough on Google Tag Manager Help: Export and import containers.

Data Collection

• Product Identifier — Select the unique backend database property (ID or SKU) to be passed as the primary item identifier to the e-commerce data layer.

• SKU Source — Determine whether the system resolves the parent identifier or the individual child variant identifier when processing complex products (such as Configurable, Grouped, or Bundle products):

• • Child — Forces the data layer to pass the unique identifier of the exact Simple Product variant selected and purchased by the customer.

  • Parent — Maps the global identifier to the parent Configurable or complex product record, consolidating variant sales under a single product profile.

• Collect child products on View (appears only when SKU Source is set to "Child") — Select Yes to automatically parse and push the entire data array of all underlying Simple Product child variations into the view_item event when a customer accesses a Configurable Product page. Select No to restrict view_item tracking exclusively to the top-level parent product data.

• Track Item Variant — Select Yes to enable the transmission of product options data (the item_variant parameter) inside the GA4 data layer.

• Item Variant Definition (appears only when Track Item Variant is set to "Yes") — Determine the exact structural logic used to format the text string for item variations:

• • Simple Product SKU — Extracts and utilizes the literal alphanumeric SKU string assigned to the selected child product.

  • Attribute Combination — Dynamically compiles a structured string based on chosen variant attributes (e.g., Size: L | Color: Red).

• Enable Brand Tracking — Select Yes to include the manufacturer brand designation within the GA4 product array.

• Brand Attribute (appears only when Enable Brand Tracking is set to "Yes") — Select the specific catalog attribute (such as Manufacturer or Brand) to bind to the brand reporting tier.

• Events tracked via Measurement Protocol (MP) — Select specific transaction and pipeline events (Purchase, Begin Checkout, Add Payment Info, Add Shipping Info) to be transmitted directly to Google Analytics via a secure server-to-server connection rather than relying on browser execution. For a deeper understanding of server-side data streams, see Google Analytics Developers: Measurement Protocol Overview.
  
  

• Tracked Order Statuses — Select the order statuses that align analytics reporting with actual warehouse operations. This acts as an operational filter for the server-side Measurement Protocol, ensuring transaction data is only transmitted when an order matches the highlighted statuses (e.g., suppressing records marked as Canceled to maintain pure revenue metrics).

• MP: Send User-ID — Select Yes to transmit the user_id parameter to Google Analytics via Measurement Protocol, allowing you to connect anonymized customer behavior across different sessions and devices.

• MP: Send User Properties — Select Yes to include customer attributes (such as customer_group) in each server-side event payload, enabling enhanced custom dimension filtering and reporting inside GA4.

• MP: Select User Properties to send (appears only when MP: Send User Properties is set to "Yes") — Select the specific visitor metadata attributes to be transmitted alongside backend analytics events, such as Browser, Browser Version, and Platform (Operating System).

Transaction & Revenue Logic

• Transaction Revenue Source — Choose which value to report as store revenue during the purchase event:

• • Subtotal — Uses the baseline cost of items before taxes and delivery fees are applied.

  • Grandtotal — Uses the final transactional amount charged to the consumer, which opens up additional dependencies for processing shipping and taxes.

• Exclude Sales Tax (appears only when Transaction Revenue Source is set to "Grandtotal") — Select Yes to automatically deduct the calculated sales tax amount from the reported revenue total before transmission to Google Analytics.

• Exclude Shipping from Revenue (appears only when Transaction Revenue Source is set to "Grandtotal") — Determine how transport and handling fees are processed inside the data layer:

• No, keep everything — Sends the entire shipping line total as part of the overall transaction calculation.

• Exclude Shipping and Shipping Tax — Fully subtracts both the base delivery costs and its associated tax line item from the final reported revenue parameter.

• Exclude Shipping Cost Only — Subtracts the delivery pricing line item from the revenue report while keeping any shipping tax amounts included.

• Exclude Zero-Value Orders (GA4) — Select Yes to filter out operations with a 0.00 value from the primary GA4 purchase tracking engine, preventing test transactions or free downloads from skewing Average Order Value (AOV) metrics.

• Exclude Zero-Value Orders (Google Ads Conversion Tracking) — Select Yes to prevent free or test orders from being captured as conversions inside Google Ads campaigns, maintaining true Conversion Rate and Return on Ad Spend (ROAS) analytics.

• Exclude Zero-Value Orders (Google Ads Remarketing) — Select Yes to filter out 0.00 value orders from the active Remarketing data layers, preserving high-value customer audience segmentations.

Event & User Dimensions

• Track Customer ID: User Dimension — Select Yes to pass the internal Magento customer identifier to the GA4 data layer.

• Track Customer Group: User Dimension — Select Yes to include the specific Magento customer segment assignment within user-level reporting parameters.

• Track Page Name: Event Dimension — Select Yes to pass the current storefront layout or specific template label into GA4 custom event tracking variables.

• Track Page Type: Event Dimension — Select Yes to classify and map the layout architecture class (such as catalog_category_view or cms_index_index) as an event modifier.

• Track Stock Status: Item Dimension (Requires GTM Retrigger) — Select Yes to append the real-time inventory status parameter into product data layers.

• Track Review Count: Item Dimension (Requires GTM Retrigger) — Select Yes to inject the quantitative total of product reviews into catalog event dimensions.

• Track Review Score: Item Dimension (Requires GTM Retrigger) — Select Yes to map the cumulative product rating metrics directly inside active shopping arrays.

• Track Sale Status: Item Dimension (Requires GTM Retrigger) — Select Yes to dynamically pass whether a product is discounted or running under a promotional price ruleset.

• Custom Dimension [1-5]: Enable (Requires GTM Retrigger) (appears only when the parent Custom Dimension block is actively set to "Yes") — Select Yes to allocate up to five specialized mapping pipelines, bridging unique custom e-commerce product attributes directly into the tracking payload data layer.

• Custom Dimension [1-5]: Parameter Name (appears only when the corresponding Custom Dimension is set to "Yes") — Enter the exact alphanumeric target variable designation mapped inside your Google Analytics dashboard setup (e.g., fabric_type).

• Custom Dimension [1-5]: Source Attribute (appears only when the corresponding Custom Dimension is set to "Yes") — Select which active catalog attribute provides the backend records for the custom tracking pipeline.

• Track Product Clicks (select_item) — Select Yes to track storefront click-through events from categories, product grids, search landing layouts, and cross-sell recommendation widgets.
  Warning: Activating click-tracking overrides core storefront template rendering files (Magento_Catalog::product/list.html). If your active theme layout or third-party catalog search extensions modify this template, layout code must be manually adjusted to prevent script processing failures.

• Internal Promotion Tracking — Select Yes to deploy a global document event listener that captures impression metrics, clicks, and performance across onsite marketing banners.

• Data storage lifetime, minutes (appears only when Internal Promotion Tracking is set to "Yes") — Enter a numerical value to determine how long collected promotional view parameters persist inside local browser memory before clearing data sessions.

Google Ads & Marketing Settings

If you modify any settings in this section, you must retrigger the Variables, Triggers, and Tags setup in your Google Tag Manager (GTM) account to apply the changes.

• Enable Google Ads Conversion Tracking — Select Yes to track successful purchase events as conversions in Google Ads. This logic is automatically bundled into the GTM JSON export. Setting this field to No disables conversion tracking and hides the secondary configuration options. To set up your conversion actions in the advertising console, see Google Ads Help: Set up conversion tracking for your website.

• Google Ads Conversion ID (appears only when Enable Google Ads Conversion Tracking is set to "Yes") — Enter your unique Google Ads ID (usually prefixed with AW-).

• Google Ads Conversion Label (appears only when Enable Google Ads Conversion Tracking is set to "Yes") — Enter the specific alphanumeric string for your purchase conversion action.

• Enable Google Ads Remarketing — Select Yes to enable data collection for remarketing campaigns. Setting this field to No disables remarketing tracking and hides the conversion label configuration field.

• Google Ads Remarketing: Conversion Label (appears only when Enable Google Ads Remarketing is set to "Yes") — Enter the specific remarketing label found in your Google Ads account to tie remarketing data to a specific audience list.

• Dedicated Google Ads Event — Select Yes to enable a standalone google_ads_conversion dataLayer event. This acts as a fallback to ensure transaction details are captured if standard GA4 purchase tags fail.

• Google Ads Conversion Currency — Select the primary currency used in your Google Ads account. This ensures conversion values are reported accurately, even if the storefront uses a different display currency.

• Enable Enhanced Conversions — Select Yes to securely send hashed customer data (such as Email and Phone) to Google Ads. This improves measurement accuracy when cookies are limited. Setting this field to No disables the option and hides secondary GA4 integration settings.

• Prerequisite: Ensure Enhanced Conversions is also enabled directly in your Google Ads account interface. To set up your conversion actions in the advertising console, see Google Ads Help: Set up conversion tracking for your website.

• Send Enhanced Conversions to GA4 (appears only when Enable Enhanced Conversions is set to "Yes") — Select Yes to include the securely hashed customer data within the purchase event sent to Google Analytics 4.

• Track New Customer Acquisition — Select Yes to populate the dataLayer with the customer's status during checkout, allowing you to optimize Google Ads bidding strategies for new customer acquisition. Setting this field to No hides the reset period parameter.

• New Customer Reset Period (Days) (appears only when Track New Customer Acquisition is set to "Yes") — Define the timeframe (e.g., 540 days) that must pass before a returning customer is recognized and tracked as a new customer again.

• Send Cart Data — Select Yes to pass item-level details within the conversion tag. This provides deeper data for Google Ads reporting and automated bidding strategies.

• Google Merchant Center ID — Enter the unique 9-to-15-digit identifier of the account where your product feeds are uploaded. For data validation requirements, see Google Merchant Center Help: Meet the product data specification.

• Google Feed Country — Select the target country associated with your Google Merchant Center product feed from the dropdown menu.

• Google Feed Language — Select the language used in your Google Merchant Center product feed from the dropdown menu.

Advanced & Debugging

• Enable Data Layer Preview — Select Yes to display a dedicated console on the frontend to monitor data layer updates and variable values in real-time. Selecting No deactivates the monitoring console and hides secondary access restrictions.

• Data Layer Preview IP Restrictions (appears only when Enable Data Layer Preview is set to "Yes") — Specify custom IP addresses (comma-separated) authorized to view the data layer console. Use an asterisk (*) to grant visibility to all visitors.

• Impression Batch Size — Define a numeric limit to split the massive view_item_list payload into smaller batches (e.g., 15). This prevents data loss caused by exceeding maximum server header size limitations. For example, setting this parameter to 15 chunks a listing of 45 items into 3 separate data layer events.

• Custom Checkout Paths — Specify unique URL paths if your store utilizes a custom or third-party checkout extension instead of the default Magento checkout route (checkout/index/index). Use commas to separate multiple paths and an asterisk (*) as a wildcard for dynamic URL segments (e.g., checkout/onestep/*, firecheckout/index/*).

• Custom Success Page Paths — Specify unique URL paths if your storefront uses a non-standard order confirmation layout instead of the native Magento success path (checkout/onepage/success). Use commas to separate distinct URLs and an asterisk (*) for dynamic tracking fragments (e.g., checkout/onestep/success, custompay/success/*).

• Use Secure Cookies — Select Yes to enable the Secure flag for tracking cookies, ensuring they are only transmitted over secure HTTPS connections.
  Note: Your site must have a valid SSL certificate and serve all storefront pages over HTTPS for this setting to function properly.

• Product Listing Compatibility Mode — Select Yes if product impressions on Category or Search pages are tracking incorrectly (e.g., due to wrong item sorting or ignoring pagination). This mode resolves data conflicts with third-party search engines or heavily customized product grids by pulling records directly from the Magento layout Block instead of the database Collection.
  
  

• Enable File Logging — Select Yes to save a local record of all dispatched analytics tracking events to the log file var/log/ga4.log within your Magento root installation directory for debugging purposes.

• Enable Debug Mode — Select Yes to append the explicit debug_mode parameter to tracked storefront interactions. This allows administrators to validate real-time events inside the GA4 DebugView console and logs server responses directly to var/log/ga4-debug-collect.log. To learn how to monitor these live feeds, visit Google Analytics Help: Monitor events in DebugView.