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 better quality measurement signals. If you have a question or issue with your setup, reach out to us at [e-mail].

First-party mode lets you deploy a Google tag using your own first-party infrastructure, hosted on your website's domain. This infrastructure sits between your website and Google's services. The setup in this documentation will help you better measure your website. You can set it up using your existing Content Delivery Network (CDN), load balancer, or web server.

In standard Google tag setups, your web page requests a Google tag from a Google domain. 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. When the tag fires, it sends measurement requests to your first-party domain, where they are forwarded to the relevant Google product.

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

To get started, pick your setup type.

Manual setup Automated setup with Cloudflare

Note: Automated setup with Cloudflare is in closed beta. Express your interest by filling out the interest form.

1. How it works

This feature adds the Google tag or Tag Manager container to the very top of your web page, before all other scripts.

If you are setting up your tag for the first time on your website, a gtag('config') or gtm.init event will be automatically added on-page. However, if your website is already using the tag, first-party mode will honor on-page setting you already configured for the tag. You can control this behavior in the Cloudflare settings for first-party mode.

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

Your domain: example.com
Measurement path: /metrics

2. Setup steps

a. Navigate to the First-party mode settings

1. Access your Google tag screen or your Google Tag Manager container
2. Go to the Admin tab
3. Open the First-party mode settings

b. Choose a Measurement Path

Caution: To avoid affecting your website, choose a path that's not already in use.

By default the measurement path is a combination of four alphanumeric characters to reduce the likelihood of conflicting with a path already on your website.

To customize the measurement path:

1. Expand the measurement path slat by clicking the arrow icon
2. Enter your custom path in the input field - /metrics

c. Sign in with Cloudflare

After choosing a measurement path, click the Sign into Cloudflare button. Log into your Cloudflare account to grant the Google tag access to deploy first-party mode.

Granting access allows the Google tag to:

1. See your account info (e.g. account details, analytics, and memberships)
2. Read your account zones
3. Read, edit, and publish Google tags in first-party mode on your site
4. Perform authorized actions in the background without your presence
   • Note: other users with Publish permission on your Google tag can update the first-party settings.

d. Enable first-party mode

Before enabling first-party mode, check that that the Cloudflare zones listed match your expectations and that your measurement path is not already in use.

After verifying your setup, click the Complete setup button at the bottom of the card to enable first-party mode for all of your Cloudflare zones.

3. Managing first-party mode

Once enabled, you can manage first-party mode using the Configure button found in the top-right card header.

Clicking the button gives you the following options:

1. Pause or Activate
   • Disables or enables first-party mode for all the domains in your Cloudflare account
2. Configure in Cloudflare
   • Opens the Cloudflare dashboard, allowing you to configure each domain independently

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

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