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.

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