Google Tag Manager (GTM)
Connect your GTM container (read-only) to check the configuration and generate the import file for ecommerce, form, outbound, scroll and download tracking.
The role of GTM in metricsKit#
metricsKit's ecommerce attribution / conversion tracking relies on your site's GTM container to send events (purchases, forms, outbound clicks…) into GA4. The GTM connection is used to:
- Check whether your container has the required configuration (the "Check configuration" action)
- Generate the import file: it contains the required triggers / tags / variables for you to import in GTM
- Generate a GTM import file (JSON) you can also import manually
Note: GTM uses the read-only scope (tagmanager.readonly): metricsKit only reads your container for checks and verification and never modifies it; creating and publishing entities is entirely up to you in GTM.
Prerequisites#
- A Google account with edit access (or higher) to the target GTM container.
- The site already has the GTM container snippets installed, or follow the setup wizard.
- The container already has a GA4 Configuration tag — create one first if missing.
- Check the GTM service during authorization.
Binding the container#
- After authorization, metricsKit lists your GTM accounts and containers; a unique domain match binds automatically.
- You can also paste the container page URL, the full path (accounts/{id}/containers/{id}), or the public ID.
- Note: API paths require the numeric internal ID; the public GTM-XXXX ID alone cannot call the API.
Tip: Accounts with container-level-only permission may not see the container in the list — bind it with the full path manually.
Deployment#
metricsKit never writes to your container (GTM is granted read-only access). The flow: download the generated "Import file" (JSON) → import it in GTM → Admin → Import Container → Submit → Publish in GTM.
Note: Importing creates duplicates if run twice: import once, or choose "Overwrite" in the import dialog. Nothing takes effect until you Submit and Publish in GTM.
Container configuration items#
The complete container configuration is as follows (identical to what the metricsKit "Import file" creates): 2 custom JavaScript variables, 4 data-layer variables, 9 triggers and 10 tags. Every tag is of type "Google Analytics: GA4 Event", using the site's bound GA4 measurement ID.
Note: Prerequisite: the container must already contain a GA4 configuration tag (Google tag / GA4 Configuration with a G-XXXXXXXXXX measurement ID). metricsKit does not create it; without it no event tag will send.
| Variable name | Type | Configuration / Data Layer name |
|---|---|---|
| metricsKit - Outbound Domain | Custom JavaScript | Compares the clicked link host with the site host to detect outbound clicks |
| mk - Affiliate Detector | Custom JavaScript | Outputs program / affiliateId / affiliateType from your AFF patterns |
| dlv - ecommerce.value | Data Layer Variable | ecommerce.value |
| dlv - ecommerce.currency | Data Layer Variable | ecommerce.currency |
| dlv - ecommerce.transaction_id | Data Layer Variable | ecommerce.transaction_id |
| dlv - ecommerce.items | Data Layer Variable | ecommerce.items |
| Trigger name | Type | Configuration |
|---|---|---|
| metricsKit - Form Submission | Form Submission | All forms |
| metricsKit - Outbound Click | Click - Just Links | Wait for tags 2000ms (timeout 2000ms); validation wait off |
| metricsKit - Scroll Depth | Scroll Depth | Vertical thresholds 25 / 50 / 75 / 100 % |
| metricsKit - File Download | Link Click | Wait for tags 2000ms; validation wait off |
| metricsKit - Ecommerce Purchase | Custom Event | Event name purchase |
| metricsKit - Ecommerce Add To Cart | Custom Event | Event name add_to_cart |
| metricsKit - Ecommerce Begin Checkout | Custom Event | Event name begin_checkout |
| metricsKit - Ecommerce View Item | Custom Event | Event name view_item |
| metricsKit - Ecommerce Refund | Custom Event | Event name refund |
| Tag name | Event name | Event parameters | Firing trigger |
|---|---|---|---|
| metricsKit - GA4 Event - Form Submit | form_submit | formId, formClasses, formText, formUrl, formDestination | Form Submission |
| metricsKit - GA4 Event - Outbound Click | click | linkUrl, linkDomain, linkText, outbound=true | Outbound Click |
| metricsKit - GA4 Event - Scroll | scroll | percent_scrolled | Scroll Depth |
| metricsKit - GA4 Event - File Download | file_download | file_name, link_url, link_text | File Download |
| metricsKit - GA4 Event - Affiliate Click | affiliate_click | affiliate=true, affiliate_program, affiliate_id, affiliate_type, link_url, link_text | Outbound Click |
| metricsKit - GA4 Event - Ecommerce Purchase | purchase | value, currency, transaction_id, items (from the dataLayer ecommerce object) | Ecommerce Purchase |
| metricsKit - GA4 Event - Ecommerce Add To Cart | add_to_cart | value, currency, transaction_id, items | Ecommerce Add To Cart |
| metricsKit - GA4 Event - Ecommerce Begin Checkout | begin_checkout | value, currency, transaction_id, items | Ecommerce Begin Checkout |
| metricsKit - GA4 Event - Ecommerce View Item | view_item | value, currency, transaction_id, items | Ecommerce View Item |
| metricsKit - GA4 Event - Ecommerce Refund | refund | value, currency, transaction_id, items | Ecommerce Refund |
Note: The import file carries the 2 custom JavaScript variables (Outbound Domain, Affiliate Detector); when ecommerce is selected it also contains the 4 dlv - ecommerce.* data-layer variables (ecommerce.value / ecommerce.currency / ecommerce.transaction_id / ecommerce.items). metricsKit never writes to your container — you import every entity in GTM.
Tip: Deployment: download the "Import file" (JSON) and import it via GTM → Admin → Import Container; GTM assigns entity IDs, then Submit → Publish. metricsKit never writes to your container (GTM is granted read-only access).
Platform guides#
- WordPress (WooCommerce / EDD, WPForms, Contact Form 7…): /docs/wordpress/gtm
- Shopify (Custom Pixel / Web Pixel support boundaries): /docs/shopify/gtm
Troubleshooting#
- Check shows all ✗: the entities are not imported yet, or imported but not published in GTM. Follow the import flow, then re-check.
- Empty container list: missing account-level access or a container-level grant — bind with the full path.
- Check shows partial: some entities are missing — re-import in GTM (or add the missing ones) and publish, then re-check.