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

Note: First-party mode is in beta. Setting up first-party mode may help your tag setup perform better, resulting in recovery of lost measurement signals, in a privacy-safe way. If you have a question or issue with your setup, reach out to us at [e-mail].

First-party mode lets you to deploy your 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 X% 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:

Before you begin

This guide assumes that your website is already configured with:

• A Google tag or Tag Manager container
• A Content Delivery Network (CDN) or load balancer that can forward requests to external endpoints

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.

Choose any path you want for setting up first-party mode. Examples of paths you might want to use include: /metrics, /securemetric, /analytics, or preferably a random alphanumeric string that you don't use on your website already.

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

Your domain: example.com
Google tag ID: GTM-123456
Tag serving path: /metrics

Caution: This setup reroutes all traffic with the chosen path. To avoid affecting your website, choose a path that's not already in use.

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.

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

Note: Tags won't use this CNAME entry; Cloudflare uses it to route requests internally.

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 GTM-123456.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... GTM-123456.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 GTM-123456.fps.goog.
2. Override the Host header to be equal to GTM-123456.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=GTM-123456"></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.

   

Step 5: Feedback

Provide feedback about first-party mode through the feedback form.