Set up First-Party Serving Path

The First-Party Serving Path feature lets you recover the unmasked user IP address by routing a request through your Content Delivery Network (CDN) or web infrastructure to Google ad servers.

On third-party requests, browser and OS features and network configurations might mask IP addresses. This masking might impact your ad revenue, geographic targeting, and invalid traffic (IVT) detection.

Your CDN receives a user's unmasked client IP on all incoming requests to your domain. This feature provides the following benefits:

  • No client-side code changes: You don't edit JavaScript or pass parameters manually. Google Publisher Tag (GPT) reads the configured path from your Google Ad Manager settings and runs the recovery request asynchronously.
  • Less overhead: The request is lightweight, cached locally per page view session, and runs asynchronously along ad slot definitions.
  • Encrypted payload: By default, this feature returns the user's IP address as an encrypted payload.

This page covers configuring the First-Party Serving Path to your preferred CDN.

Prerequisites

Before configuring your CDN, do the following:

  • Specify a serving path in your Ad Manager account, for example, /adserver/. To specify the path, follow the steps in Method 1: First-party serving path.
    • Make sure that your serving path is unique, and no traffic you send uses this path.
  • Have or set the following items:
    • Target host or origin: securepubads.g.doubleclick.net
    • Target path: /pagead/fpm
    • Protocol: HTTPS with the default port 443.
    • Headers: Set the header as Host: securepubads.g.doubleclick.net.
    • Caching: Configure your CDN to bypass caching for a route, for example, set the cache policies to bypass cache or the Cache-Control: no-store header.
  • If your CDN is Cloudflare, you must have a Cloudflare Enterprise tier to create an origin rule.

Configure your CDN

Configure your CDN or reverse proxy to forward requests matching your configured path to Google ad servers. Select your preferred CDN:

Cloudflare

  1. Create a rule in the dashboard with the following values:

    • Custom filter expression: Add the following:
      • Field: URI Path
      • Operator: starts with
      • Value: your path, for example, /adserver/.
    • Host Header Override: Select Rewrite to and add the target host securepubads.g.doubleclick.net.
    • DNS Override: Select Override to and add the target host securepubads.g.doubleclick.net.

  2. Create a URL rule rewrite in the dashboard with the following values:

    • Custom filter expression: Add the following:
      • Field: URI Path
      • Operator: starts with
      • Value: your path, for example, /adserver/.
    • Path: Select Rewrite to > Static > and add the /pagead/fpm target path.
    • Query: Select Preserve.

Amazon CloudFront

  1. Follow the steps in Origin settings with the following values:

    • Origin domain: securepubads.g.doubleclick.net
    • Protocol: HTTPS

  2. Follow Create functions and add the following example:

    function handler(event) {
    var request = event.request;
    request.uri = '/pagead/fpm';
    return request;
}

    This example takes the incoming request event, assigns the URI to the target path, and returns the request.

    Click Save changes, navigate to the Publish tab, and click Publish function.

  3. Follow Update a distribution in the console with the following values:

    • Path pattern: your path, for example, /adserver/*.
    • Origin and Origin Groups: the target host, securepubads.g.doubleclick.net.
    • Cache policy: Select CachingDisabled.
    • Origin request policy: Select AllViewerExceptHostHeader.
    • Function associations:
      • Viewer request: Select CloudFront Function and add the name of your function.

Fastly

  1. Follow Adding a host with the following values:

    • Address: the target host, securepubads.g.doubleclick.net
    • Port: the default port, 443.
    • Enable TLS?: Yes
      • Certificate hostname: securepubads.g.doubleclick.net
        • Select Match the SNI hostname to the Certificate Name.
      • SNI hostname: securepubads.g.doubleclick.net
      • Override host: securepubads.g.doubleclick.net

  2. Follow Creating VCL snippets with the following example:

    if (req.url ~ "^PATH") {
    set req.backend = F_NAME;
    set req.http.Host = "securepubads.g.doubleclick.net";
    set req.url = regsub(req.url, "^PATH", "/pagead/fpm");
    return(pass);
}

    Replace the following:

    • NAME: the name of the host, for example, Google_GAM_FPM_Backend.
    • PATH: your path, for example, /adserver/.

Google Cloud

  1. Follow Create the NEG and internet endpoint with the following values:

    • Network endpoint group type: Select Internet NEG (Global)
    • Default port: 443
    • New network endpoint: Select Fully qualified domain name (FQDN) and port.
    • FQDN: add the target host, securepubads.g.doubleclick.net.

  2. Create your global backend service and configure custom request headers with the following values:

    • Backend type: Select Internet network endpoint group.
    • Protocol: Select HTTPS.
      • Header name: Host
      • Header value: add the target host, securepubads.g.doubleclick.net.

  3. Follow the steps in Configure URL maps.

  4. In Routing rules, locate your production host rule that matches your subdomain.

    Update the path matchers with the routeRules configuration:

    name: NAME
defaultService: projects/PROJECT_ID/global/backendServices/DEFAULT_BACKEND
routeRules:
  - priority: 1
    matchRules:
      - prefixMatch: PATH
    service: projects/PROJECT_ID/global/backendServices/BACKEND_NAME
    routeAction:
      urlRewrite:
        pathPrefixRewrite: /pagead/fpm

    Replace the following:

    • BACKEND_NAME: the name of the backend service you created in step 2, for example, gam-fpm-backend-service.
    • DEFAULT_BACKEND: the default backend service that hosts your website.
      • If you host your website on Cloud Storage, replace backendServices with the backendBuckets parameter in the resource path of the defaultService field.
    • NAME: the name of the path matcher, for example, gam-fpm-matcher.
    • PATH: your path, for example, /adserver/.
    • PROJECT_ID: your project ID.

Test your implementation

To verify your CDN proxies the request and passes the IP address, run a test using the curl command:

curl -i https://example.comPATH

Replace PATH with your path, for example, /adserver/.

If successful, you receive the following output:

  • HTTP status: 200 OK
  • Response content: A payload from Google backend servers that contains an encrypted IP token by default.

Troubleshoot your implementation

This section covers workflows to troubleshoot your First-Party Serving Path implementation in your CDN.

The following table details issues, causes, and solutions to troubleshoot:

Issue Cause Solution
You receive the HTTP status 404 or 502 from your CDN Path rewrite is not active or the Host header is missing. Verify your rewrite maps to the /pagead/fpm target path and Host header is overridden to the target host, securepubads.g.doubleclick.net.
The IP address isn't updated on ad requests. Caching enabled on CDN proxy Make sure you set the cache policy on the route to the CachingDisabled policy or the Cache-Control: no-store header. Every client must reach the backend service to evaluate their specific IP address.
SSL or TLS handshake failure SNI mismatch on backend origin connection Make sure you configured your CDN to send the target host securepubads.g.doubleclick.net in the TLS SNI extension.
Missing the ips parameter in the ad request. Ad Manager path doesn't match CDN path Verify that the path entered in the Ad Manager UI Global Settings page matches the path configured on your CDN. For details, see Pass unmasked publisher-provided IP (Beta).