Skip to main content

Google Ad Manager Secure Signals Integration Guide

This guide covers integration steps for publishers using UID2 with the Google Ad Manager secure signals feature (previously known as Encrypted Signals for Publishers, ESP).

note

To use the UID2 Google Ad Manager secure signals integration, if you are using an SDK you must have your UID2 integration already set up. This does not apply if you are using server-side integration. For a summary of all the integration options available, see UID2 Integration Guides: Summary.

Overview​

Google secure signals is a way for publishers to pass "encrypted" user IDs to bidders that are approved by Google, via Google Ad Manager and the Google Ad Manager Ad Exchange (AdX). The framework is an optional part of the Google Publisher Tag (GPT) library commonly used by publishers.

With this framework, the following steps occur:

  1. Publishers push user ID signals (advertising tokens) to the secure signals feature.
  2. The secure signals feature caches them on the client side and then transparently passes them to Google Ad Manager.
  3. Google Ad Manager uses the UID2 tokens to make bid requests, forwarding the tokens to approved bidders within Google AdX based on the publisher's preferences.

Complete UID2 Account Setup and Configure Account​

To integrate with UID2, you'll need to have a UID2 account. If you haven't yet created an account, first follow the steps described on the Account Setup page.

When initial account setup is complete, you'll receive instructions and a link to access the UID2 Portal, where you can create your credentials for the production environment and configure additional values, if needed. For details, see Getting Started with the UID2 Portal.

The specific values you set up will depend on which of the publisher integration options you choose:

Allow Secure Signals Sharing​

For your Google Ad Manager account to be eligible to receive encrypted UID2 tokens, you must make sure that encrypted signals are properly shared with third-party bidders on your Google Ad Manager account.

For details, see Share encrypted signals with bidders in the Google documentation, and then follow the steps in Use a third-party signal provider to switch on UID2 as your signal provider.

important

When you're following the steps, in Select allowed secure signals, under Web Signal Deploy Option, choose Google Deploy. If you're using Prebid.js, see Optional: Enable Secure Signals in Prebid.js.

Optional: Enable Secure Signals in Prebid.js​

If you want to use Secure Signals with Prebid.js, you must complete both these additional steps so that your UID2s are correctly processed:

  1. In Google Ad Manager, when you're making sure that encrypted signals are properly shared with third-party bidders: Choose the Prebid User ID Module, and then also choose Use your Prebid configuration to automatically configure your Secure signals settings. Before saving your configuration, double-check that you've selected the correct option.

  2. In your Prebid.js setup: update the encryptedSignalSources section in your Prebid configuration, as shown in the following code:

    "encryptedSignalSources": {
      "sources":[
        {
          "source":[
            "uidapi.com"
          ],
          "encrypt":false
        }
      ]
    }

    For details, see ESP Configurations in the Prebid documentation.

Integrating with Single Sign-On (SSO)​

If you integrate with one or more SSO providers to offer SSO login, you might be able to retrieve the logged-in user's email address from the SSO provider to generate UID2 tokens.

For details, see Publisher Integration with SSO Providers.

Publisher Integration​

When an encrypted signal is cached, the secure signals feature does not execute the handler to generate a new signal. Because of this, it is necessary to clear the cache before and after data capture.

Since the secure signals feature does not provide a way to delete or invalidate a specific ID, publishers must call the window.googletag.secureSignalProviders.clearAllCache() function to clear all shared encrypted signals as part of their data capture workflows.

The following is an example of calling the window.googletag.secureSignalProviders.clearAllCache() function:

window.googletag = window.googletag || { cmd: [] };
window.googletag.cmd.push(function () {
  window.googletag.secureSignalProviders =
    window.googletag.secureSignalProviders || [];
  window.googletag.secureSignalProviders.clearAllCache();
});

Publisher Integration Options​

There are three integration options for Google Secure Signals publisher integration with UID2:

Server-Side Integration​

So that it can share encrypted signals, the hosted auto-loaded secure signals script must be able to make an asynchronous call to the window.getUid2AdvertisingToken function and, in response, receive advertising_token as a string.

It's important to make sure that the identity token is fresh. For a server-side integration, we recommend making a call to the POST /token/refresh endpoint to get a fresh advertising token from the JSON response.

The following code is an example of how you could do this.

window.getUid2AdvertisingToken = async () => {
  // Make a call to get a fresh identity token which could last for at least 12 hours.
  const identity = await getFreshIdentity()
  return JSON.parse(decodeURIComponent(identity)).advertising_token
}

For details, see Publisher Integration Guide, Server-Side.

A sample implementation is also available for server-side integration. See Sample Implementations.

SDK for JavaScript Client-Server Integration​

If you're using the SDK for JavaScript version 3.0.0 or later, the UID2 secure signals script uses the getAdvertisingTokenAsync function provided in the SDK to get the fresh advertising token, and then pushes the token to Google Ad Manager.

This script is hosted on CDN, and GPT automatically loads it with the secure signals feature.

For details, see Client-Server Integration Guide for JavaScript.

A sample implementation is also available for integration using the SDK for JavaScript. See Sample Implementations.

SDK for JavaScript Client-Side Integration​

If you're using the SDK for JavaScript version 3.0.0 or later, the UID2 secure signals script uses the getAdvertisingTokenAsync function provided in the SDK to get the fresh advertising token, and then pushes the token to Google Ad Manager.

This script is hosted on CDN, and GPT automatically loads it with the secure signals feature.

For details, see Client-Side Integration Guide for JavaScript.

Sample Implementations​

The following sample implementations are available to illustrate how to integrate with the Google Ad Manager secure signals feature:

Each sample implementation has its own instructions.

Troubleshooting​

Here is some troubleshooting information that might help you in working with Google secure signals for your UID2 integration:

I enabled Secure Signals within Google Ad Manager, but UID2s are not being passed through Google​

In some cases, after choosing Secure Signals within Google Ad Manager, successful UID2s were not being passed through Google because the participant had an incorrect Web Signal Deployment Method configuration.

If your UID2s are not being passed through Google, make sure that you chose the correct Web Signal Deployment Method during setup.

For details, see the Important note in Allow Secure Signals Sharing.