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](https://developers.google.com/tag-platform/tag-manager/server-side/first-party-tagging) 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-XXXXXX` retrieves the GTM initialization script
- **Measurement hits** — e.g. `POST /metrics/g/collect` sends 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](store-variables) access

## Configure the gateway

Add the following [Store variables](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](adding-custom-javascript-css-and-head-content) 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](liquid-controllers) for details.

## Troubleshooting

- **Requests not being proxied**: Verify both `gtm_gateway.host` and `gtm_gateway.path` store variables are set. The gateway is disabled if either is missing.
- **Host validation error**: The `gtm_gateway.host` value 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.