Google Tag Manager first-party gateway
On this page
StoreConnect includes a built-in first-party gateway for Google Tag Manager (GTM). When configured, GTM script requests and measurement hits are proxied through your store’s own domain instead of Google’s servers. This helps avoid ad blockers and browser tracking restrictions (such as Intelligent Tracking Prevention) that commonly block third-party analytics requests.
:::note This feature requires your Google account to have server-side tagging and a first-party domain configured in Google Tag Manager. See Google’s first-party mode documentation for setup instructions. :::
How the gateway works
Once configured, requests to a path on your store domain (e.g. https://yourstore.com/metrics/) are transparently proxied to your GTM first-party host (*.fps.goog). This covers both:
- Script downloads — e.g.
GET /metrics/gtag/js?id=G-XXXXXXretrieves the GTM initialization script - Measurement hits — e.g.
POST /metrics/g/collectsends event data to Google Analytics
Your customers’ browsers only communicate with your domain; the proxy forwards requests to Google on their behalf.
Prerequisites
- A Google Tag Manager account with server-side tagging configured
- A first-party GTM host provisioned by Google (format:
gtm-XXXXXX.fps.goog) - A StoreConnect store with Store variables access
Configure the gateway
Add the following Store variables to your store:
| Variable | Value | Description |
|---|---|---|
gtm_gateway.host |
Your fps.goog hostname (e.g. gtm-abcdef.fps.goog) |
The first-party GTM host provisioned by Google. Must end in .fps.goog. |
gtm_gateway.path |
URL path prefix (e.g. metrics) |
The path under which GTM requests will be served on your domain. Do not include leading or trailing slashes. |
With the example values above, requests to https://yourstore.com/metrics/ are proxied to https://gtm-abcdef.fps.goog/metrics/.
Add the GTM initialization script
After configuring the store variables, add the GTM initialization script to your store using a Script block or the store’s Head Content field. Replace the standard Google Tag Manager script URL with your proxied path:
html
<script async src="/metrics/gtag/js?id=G-XXXXXXXXXX"></script>
<script>
window.dataLayer = window.dataLayer || [];
function gtag(){dataLayer.push(arguments);}
gtag('js', new Date());
gtag('config', 'G-XXXXXXXXXX');
</script>
Replace metrics with the path you configured in gtm_gateway.path, and G-XXXXXXXXXX with your Google Analytics measurement ID.
Built-in ecommerce events
StoreConnect automatically fires the following ecommerce events through the event system when GTM is configured:
| Event | When it fires |
|---|---|
purchase |
When a customer completes a checkout and an order is confirmed |
cart.add |
When a customer adds a product to their cart |
The purchase event includes transaction details (order reference, total, tax, shipping) and a line item for each product in the order.
Custom events can be added by theme developers using Liquid controller templates. See Liquid controllers for details.
Troubleshooting
- Requests not being proxied: Verify both
gtm_gateway.hostandgtm_gateway.pathstore variables are set. The gateway is disabled if either is missing. - Host validation error: The
gtm_gateway.hostvalue must end in.fps.goog. Other domains are rejected to prevent security issues. - Upstream errors: If Google’s fps.goog service is unavailable, the gateway returns a 502 error. The store remains operational — only analytics collection is affected.