Google Tag Manager first-party gateway

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-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.

What the gateway sends to Google

Because the gateway sits on your own domain, the request it forwards is not the same as the one the browser made. Knowing what reaches your tagging server matters: a server-side container is yours to configure, its tags can forward request data on to other destinations, and container access often sits with a marketing team or an agency.

Cookies

Only Google’s own measurement cookies are forwarded. Your store’s cookies, including the shopper’s session cookie, are held back.

Cookie	What it is
_ga, _ga_<container>	GA4 client ID, plus one per container
_gid	GA visitor ID
_gat, _gat_<name>	GA request throttling
_gac, _gac_<id>	Google Ads conversion linker
_gcl_<type>	Google Ads click IDs, such as _gcl_au and _gcl_aw
FPID, FPLC, FPAU	Server-side first-party identifiers
FPGCL<type>	Server-side Google Ads click IDs, such as FPGCLAW

The match is on the cookie name exactly, so a cookie of your own that merely starts with one of these stems is not forwarded.

Headers

Alongside the cookies, the gateway forwards the browser’s User-Agent and Accept headers, and adds X-Forwarded-Country when your CDN supplies the visitor’s country. Cloudflare, Fastly and CloudFront are each read for that.

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 through the content block the store’s HTML Head Content Block field points to. Replace the standard Google Tag Manager script URL with your proxied path:

```html

```

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.

Track Google Ads conversions

The purchase event fires whenever the gtag function is defined on the page, whether you load Google’s script through this gateway or directly as described in Integrate Google Analytics in your store. There are two ways to turn it into a Google Ads conversion. Use the first unless you have a reason not to.

Import the GA4 purchase event (no code)

1. In Google Ads, link your Google Ads account to the GA4 property that receives your store’s data (Admin > Linked accounts).
2. Go to Goals > Conversions > Summary and click New conversion action.
3. Choose Import > Google Analytics 4 properties > Web, select the purchase event, and save.

Every purchase event carries transaction_id (the order reference), value, currency, tax, shipping, affiliation (the store name) and a line for each product, so Google Ads deduplicates repeat page loads and reports revenue without any further setup. Conversions appear in Google Ads within a day of the first import.

Fire the Google Ads conversion tag directly

Use this if you need the Google Ads tag to fire independently of GA4. It requires a theme change, so it is a task for whoever maintains your theme.

1. In the head script above, add a second config line for your Google Ads conversion ID inside the same <script> block, after the GA4 one:

   ```js

   gtag(‘config’, ‘G-XXXXXXXXXX’); gtag(‘config’, ‘AW-XXXXXXXXX’); ```

2. In your theme, create a Theme Template with the key snippets/events/purchase. A client theme template with the same key as a base template replaces it (see Theme structure and Theme templates), so the snippet must keep the events the base version already sends. Copy the whole of your current snippets/events/purchase content into the new template before you add anything. It holds three separate blocks: the Google purchase event, a Facebook Pixel Purchase event, and a Google Customer Reviews opt-in. Copying only the Google block silently drops the other two, with no error to tell you. Then add this block at the end, replacing AW-XXXXXXXXX/YYYYYYYYYYYY with the conversion ID and label from the conversion action in Google Ads:

```liquid

{%- if order != blank %} {%- endif %} ```

1. Place a test order and confirm the conversion in Google Ads under Goals > Conversions, or watch the conversion hit in the browser’s network tab while the order confirmation page loads.

order.total, order.currency_code and order.reference are the same values the base snippet already uses for the GA4 purchase event, so the two reports agree.

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. StoreConnect caches the gateway settings for up to 5 minutes, so a new or changed value can take that long to apply.
• Host not accepted: The gtm_gateway.host value must be a bare hostname ending in .fps.goog, such as gtm-abcdef.fps.goog. Any other value, including one with https:// or a path, is ignored without an error message, and the gateway stays disabled. 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.
• A tag needs a cookie that is not arriving: only the cookies listed in What the gateway sends to Google reach the tagging server. A tag that depends on one of your store’s own cookies cannot read it through the gateway, and needs the value passed as an event parameter instead.