Set up first-party mode

This document is for users who want to deploy the Google tag in first-party mode. We recommend first-party mode for the most durable tag configuration.

Overview

First-party mode lets you deploy a Google tag using your own first-party infrastructure, hosted on your website's domain (e.g., example.com). This infrastructure sits between your website and Google's services, making your first-party infrastructure the only technology to interact directly with your website users. First-party mode adds a layer of data security and enables additional data privacy controls—such as full IP obfuscation—without compromising your measurement. The setup in this documentation will help you recover more measurement signals on your website. You can set it up using your existing Content Delivery Network (CDN), load balancer, or web server, to enable first-party mode.

In standard Google tag setups, your web page requests a Google tag from a Google domain (e.g., www.googletagmanager.com). When the tag fires, it sends measurement requests directly to the Google product. In first-party mode, your website loads the Google tag from your first-party domain (e.g., example.com). When the tag fires, it sends measurement requests to your first-party domain, where they are forwarded to the relevant Google product.

You will experience full measurement continuity when switching from a standard Google tag setup to first-party mode configuration.

This diagram represents the information flow in first-party mode:

first-party mode architecture

Before you begin

This guide assumes that your website is already configured with:

1. Choose the tag serving path

You must reserve a path on your website domain for serving the tag. Make sure this path is not already in use on your domain.

To set up first-party mode, choose any path that isn't already in use on your site. To reduce the likelihood of conflicting with a path already on the site, you could choose any combination of letters and numbers, or if you want a more readable path, you could choose to use a word such as /metrics, /securemetric, /analytics, or any other word you want.

Fill in the following to populate the examples throughout this document.

Your domain: example.com
Google tag ID: G-12345
Tag serving path: /metrics

2. Route traffic

This section assumes that your website is already using a CDN or load balancer that supports routing traffic by paths.

Google Cloud

You need to set up a new backend that looks up the approximate geographic location of the site visitor and create routing rules in your existing External Application Load Balancer.

Create the new backend

  1. Open GCP load balancer

  2. In your load balancer, open the Backend configuration section. Create a new backend service. Screenshot of the backend config settings

  3. Configure your new backend service with geolocation information:

    • Specify a name, such as measurement-be-svc.
    • Set Backend type to Internet network endpoint group.
    • Set Protocol to HTTPS and leave Timeout as the prefilled value.
    • Under Backends, click the Internet network endpoint group drop-down and create a new internet network endpoint group:
      • Set Network endpoint group type to Internet NEG (Global, Regional).
      • Set Scope to Global.
      • Set Add through to Fully qualified domain name and port.
      • Set Fully qualified domain name to G-12345.fps.goog.
      • Click CREATE to create the endpoint.
      • Close the Network endpoint group tab to return to the New backend service tab.
    • Search the name of the new network endpoint group and select it.
    • Open the Advanced configurations section. Add the following custom request headers.
      Header name Header Value
      Host G-12345.fps.goog
      X-Gclb-Country {client_region}
      X-Gclb-Region {client_region_subdivision}
    • Review the other settings. Neither Cloud CDN nor Cloud Armor are required for this integration, so you may safely disable both.
    • Save the new backend service.

Configure routing rules

  1. In your load balancer, open the Routing rules section.

  2. Add the following host and path rules:

    Host Path Backend
    * /metrics/* measurement-be-svc

  3. Update the load balancer configuration.

  4. In a browser, verify the set up by navigating to: https://example.com/metrics/healthy. The page should have the text ok. Verify that geographical information is being included by navigating to: https://example.com/metrics/?validate_geo=healthy. The page should have the text ok.

Cloudflare

To serve your tag in first-party mode, you will create a CNAME entry for a new subdomain, create an Origin Rule to forward requests, and create a Transform Rule to include geolocation information.

Create CNAME entry

Choose a subdomain to reserve for the CNAME entry. Fill in the following to populate the examples throughout this document. This CNAME is never exposed outside your Cloudflare configuration, so the name is arbitrary.

CNAME subdomain: fps
  1. In the DNS tab, open the Records section.
  2. Add a new record with the following configuration:
    • Set Type to CNAME.
    • Set Name to fps.
    • Set Target to G-12345.fps.goog.
  3. Save the CNAME record.

Create the Origin Rule

  1. In the Rules tab, open Origin Rules and create rule.
  2. Enter a rule name, such as Route measurement.
  3. Match incoming requests based on a Custom filter expression and click Edit expression.
  4. Paste the following expression in the builder: (http.host eq "example.com" and starts_with(http.request.uri.path, "/metrics"))
  5. Update the Host Header to Rewrite to... G-12345.fps.goog.
  6. Update the DNS Record to Override to... fps.example.com.
  7. Save the Origin Rule.
  8. If there are other Origin Rules, increase the newly created Rule's position so that it will run after any other wildcard paths.
  9. In a browser, verify the setup by navigating to: https://example.com/metrics/healthy. The page should read ok.

Include geolocation information

  1. In the Rules tab, open Transform Rules.
  2. Create a Modify Request Header rule.
  3. Apply the rule to All incoming requests.
  4. Modify request header with the following configuration:
    • Set operator to Set dynamic.
    • Set Header name to X-CfIpCountryRegion.
    • Set Value to ip.src.subdivision_1_iso_code.
  5. Deploy the Transform Rule.
  6. Wait a few minutes for the rule to propagate. In a browser, verify the set up by navigating to: https://example.com/metrics/?validate_geo=healthy. The page should read ok.

(Optional) Remove visitor IP headers

First-party mode does not require visitor IP to correctly operate. You can remove all visitor IP headers by using the Remove visitor IP headers Managed Transforms.

Other

To serve your tag in first-party mode, you need to configure your CDN or load balancer to route requests to the first-party mode endpoint.

  1. Add an origin or backend that points to G-12345.fps.goog.
  2. Override the Host header to be equal to G-12345.fps.goog. Allow all cookies and query strings to be forwarded.
  3. Add a path rule for /metrics/* to route traffic to first-party mode.
  4. Configure the reserved path to have higher priority than the default rule.
  5. In a browser, verify the set up by navigating to: https://example.com/metrics/healthy. The page should read ok.

Step 3: Update the scripts on the website to use the Measurement Path

Replace the scripts on each page of the website with one of the following:

gtag.js

At the top of the <head> section, find the two lines of script with your Google tag ID:

<!-- Google tag (gtag.js) -->
<script async src="https://www.googletagmanager.com/gtag/js?id=G-12345"></script>

and replace them with the measurement path instead:

<!-- Google tag (gtag.js) -->
<script async src="/metrics/"></script>

gtm.js

At the top of the <head> section, replace the Tag Manager snippet with the following:

<!-- Google Tag Manager -->
<script>(function(w,d,s,l,i){w[l]=w[l]||[];w[l].push({'gtm.start':
new Date().getTime(),event:'gtm.js'});var f=d.getElementsByTagName(s)[0],
j=d.createElement(s),dl=l!='dataLayer'?'&l='+l:'';j.async=true;j.src=
'/metrics/?id='+i+dl;f.parentNode.insertBefore(j,f);
})(window,document,'script','dataLayer','');</script>
<!-- End Google Tag Manager -->

Step 4: Test the measurement set up

To test the measurement set up, configure your container to have at least one tag that fires.

  1. Go to Tag Assistant and preview your container. Navigate through your site to trigger tags.

  2. In the Summary > Output > Hits Sent tab, verify that the hits are routed to /metrics.

    Screenshot verifying the setup