Share consent and load/refresh ads

Our integration with Google Ad Manager which relies on passing an NPA parameter to ad requests is still available in the Didomi Console. But we do not advise using it. Please review our Google Ad Manager implementation recommendation here. This module does not support automatically passing CCPA Do Not Sell Status to Google products yet. See https://support.google.com/adsense/answer/9598414 for more information.

Didomi supports sharing consent with Google Ad Manager, AdSense and Ad Exchange asynchronous ad tags. When the user gives consent, the Google tags are configured to fetch personalized ads.

For this integration to work, you need to make sure that you are delaying the loading of Google ads until Didomi has shared the consent information with Google.

With this integration, Didomi will do two operations for you:

• Share the consent status with Google

• Refresh/load the ads on the page

Didomi must be in control of the initial loading of ads on the page to guarantee that consent has been passed to Google before the ads are loaded. You must not refresh the ads yourself or have any other tag refresh ads on the page or you will see the ads refreshed multiple times.

The Didomi SDK only synchronizes with Ad Manager. If you need to wait for other scripts to complete before loading or refreshing Ad Manager ads (for instance, wait for auction results from Prebid to integrate them into your Ad Manager ad slot), use our Ad Manager integration and control the ads yourself.

Configure the Didomi tag

If you are using the Didomi Console to manage your consent notices, you can manage the Google integration from there and can skip this tag configuration section.

You must ensure that the Didomi tag gets embedded first on your pages and configure it to communicate with the Google tag.

Enable the Didomi / Google integration

Make sure that you add the following vendors to your tag (in the app.vendors property):

• googleas a Didomi vendor (app.vendors.didomi property)

• All the "ad technology providers" enabled in your Google account (see the Google Ad Manager documentation or the Google AdSense documentation). They can be added as IAB vendors (recommended if they are in the list), Didomi or custom vendors, and must appear in the list for the consent to be valid.

You also need to enable the specific integration with Google with the property integrations:

<script type="text/javascript">
window.didomiConfig = {
  app: {
    apiKey: '<Your API key>',
    vendors: {
      iab: {
        include: [
          ..., // All the vendors that you have enabled as ad technology providers in your Google account
        ]
      },
      didomi: [
        // Ask Didomi to collect consent for Google
        'google'
      ]
    }
  },
  
  integrations: {
    vendors: {
      // Setup the integration with Google (ask Didomi to share consent with Google tags)
      google: {
        enable: true,
        eprivacy: true
      }
    },
    refreshOnConsent: true // by default, ads are reloaded after consent is given
  }
};
</script>

This configuration will tell the Didomi tag to automatically share consent with Google and resume ad loading as soon as possible by calling window.googletag.pubads().refresh() . If you are already doing manual ads refresh, you must remove them to avoid the ads from being refreshed multiple times.

You can disable the reload of the ads after consent is given by setting refreshOnConsent to false. In that scenario, Didomi will not refresh ads after consent is collected but will refresh ads on subsequent page loads.

integrations.google is required

It is used to tell the Didomi SDK to enable the integration with the Google tag. If you do not add that object, consent will be collected for Google but will not be shared with their tag.

Display ads before collecting consent

According to Google's documentation and to be compliant with the ePrivacy directive from 2002/2009, even when configured to serve non-personalized, their tags still use cookies for "frequency capping, aggregated ad reporting, and to combat fraud and abuse".

As a result, no ad request should be sent to Google (and no ad displayed) until the user has given consent for the cookies purpose. This is the default and recommended behavior. If you do not want to apply the ePrivacy directive, you can turn the eprivacy parameter to false and non-personalized ads will be served when there is no consent.

Example:

<script type="text/javascript">
window.didomiConfig = {
  app: {
    apiKey: '<Your API key>',
    vendors: {
      iab: {
        include: [
          ..., // All the vendors that you have enabled as ad technology providers in your Google account
        ]
      },
      didomi: [
        // Ask Didomi to collect consent for Google
        'google'
      ]
    }
  },
  
  integrations: {
    vendors: {
      // Setup the integration with Google (ask Didomi to share consent with Google tags)
      google: {
        enable: true,
        eprivacy: false // Serve non-personalized ads to users before collecting consent
      }
    },
    refreshOnConsent: true // by default, ads are reloaded after consent is given
  }
};
</script>

Single-page applications

The Didomi SDK has been tested with single-page applications (Angular and React) without any issue.

One important note regarding the Ad Manager integration for SPAs is that the Didomi SDK will only refresh ads once when the page/app is loaded in the browser. If you are using a custom routing logic and not actually loading new pages when the user is navigating, you must continue refreshing the Ad Manager ads yourself as you (most likely) already do.

In that case, you only want to refresh after Didomi has collected consent. You can do so by using the getUserConsentStatusForVendor function to check if Didomi already has consent or not.

Run the following snippet of code when the user navigates to another route:

// Wrap your existing Ad Manager refresh logic on user navigation
if (Didomi) {
  const vendorsWithKnownConsentStatus = Object.values(Didomi.getUserStatus().vendors.consent).flat();
  if (vendorsWithKnownConsentStatus.includes('google') {
    // Didomi is loaded and has collected consent (either positive or negative)
    // Refresh Ad Manager ads
  }
}

Google's additional consent mode (IAB TCF)

The Didomi SDK supports Google's additional consent mode.

It allows collecting consents for Google Ad vendors which are currently not part of the IAB TCF but are part of Google's Ad Tech Providers list (ATP).

By default, the Didomi SDK uses a predefined list of Google's Ad Tech Providers when generating positive and negative additional consent values.

If you would like to specify a custom positive or negative additional consent parameter, you can do so by specifying additionalConsent.positive and additionalConsent.negative fields in the google section of the Didomi's vendors configuration:

<script type="text/javascript">
  window.didomiConfig = {
    app: {
      vendors: {
        iab: {
          version: 2
        },
        didomi: ['google'],
        google: {
          additionalConsent: {
            positive: 'positive-additional-consent',
            negative: ''
          }
        }
      }
    }
  };
</script>

app.vendors.google.additionalConsent.positive is the exact AC string to pass to Google when the user has given consent to the vendor Google and all its required purposes based on consent.

app.vendors.google.additionalConsent.negative is the exact AC string to pass to Google when the user has denied consent to the vendor Google or any of its required purposes based on consent.

If the positive/negative additional consent strings are missing from the configuration, the Didomi SDK uses the predefined ATP list.

Additional consent string format

The additional consent string contains 3 parts:

• A specification version number, such as "1"

• A separator symbol "~"

• A dot-separated list of user-consented Google Ad Tech Providers

For example, the additional consent string 1~7.11.12 means that the user has consented to ATPs with IDs 7, 11, and 12, and the string is created using the format defined in the v1.0 specification.

You can find the latest Google's Ad Tech Providers (ATP) list here.

Configure your Google account

Whether you are using Ad Manager or AdSense, your need to configure your account to allow personalized ads.

Ad Manager account configuration

Sign into Google Ad Manager, go to Admin EU user consent and ensure that your account is setup for serving personalized ads (see instructions from Google on https://support.google.com/dfp_premium/answer/7673898).

The Didomi CMP will take care of enabling personalized or non-personalized ads on a per-request basis but your account must be configured to allow serving personalized ads. Otherwise, only non-personalized ads will be served no matter what the consent status of the user is.

Also note that you must identify all the vendors used by Google for serving ads and add them to your Didomi tag configuration to make sure that consent is collected for everyone of them.

AdSense account configuration

Sign into Google AdSense, go to Allow & block ads Content All my sites EU user consent and ensure that your account is setup for serving personalized ads (see instructions from Google on https://support.google.com/adsense/answer/7670013).

The Didomi CMP will take care of enabling personalized or non-personalized ads on a per-request basis but your account must be configured to allow serving personalized ads. Otherwise, only non-personalized ads will be served no matter what the consent status of the user is.

Also note that you must identify all the vendors used by Google for serving ads and add them to your Didomi tag configuration to make sure that consent is collected for everyone of them.

Configure Google tags

Google offers multiple SDKs and tags to load ads on your website. Each tag type has to be integrated slightly differently. The following instructions go through every tag type that we currently support.

You must ensure that ads do not get loaded before Didomi has shared the consent information with Google.

Fast loading of ads outside of the EU (if you are not an EU company)

If the end user is not in the EU and you are not an EU-based company, Didomi will immediately resume loading ads as no consent is required.

If you want to optimize your ad delivery, you can decide not to delay the loading of ads when the user is outside of the EU and not rely on Didomi for that. If your company is based in the EU then you must apply GDPR to all visitors and cannot leverage this option.

Ad Manager GPT tag

Update your existing Ad Manager GPT tag to disable the initial loading of ads and setup async rendering. Also remove any call to googletag.pubads().refresh() in your code as the Didomi tag will now take care of refreshing ads when needed.

Example:

googletag.cmd.push(function() {
    googletag.defineSlot(...);
    googletag.pubads().disableInitialLoad();
    googletag.pubads().enableAsyncRendering();
    googletag.pubads().enableSingleRequest();
    googletag.enableServices();
});

The Didomi tag will automatically call googletag.pubads().refresh() when consent information becomes available to trigger the rendering of the ads. The SDK will only call that function after googletag.enableServices() has been called so that there is no race condition if the SDK loads faster than Google's tag.

If you have a complex Ad Manager setup or want to control the refreshing of the ads, you can disable the integration by removing the integrations.google part of your Didomi configuration. Keep google as a vendor to make sure consent is collected for Google.

You then need to make sure you are enabling personalized ads and refreshing ads with the Ad Manager API. See https://support.google.com/adsense/answer/7670312 for more information.

AdSense / Ad Exchange tag

Make sure that you use the async ad tag and disable the initial loading of ads before you embed Google's tag:

(adsbygoogle=window.adsbygoogle||[]).pauseAdRequests=1;

The Didomi tag will automatically set window.adsbygoogle.pauseAdRequest=0 to resume ad loading when consent information becomes available to trigger the rendering of the ads.

The order of execution matters

You must set pauseAdRequests to 1 before the tags from Google and Didomi get loaded. Because the Didomi SDK will set the value back to 0, there could be a race condition where you would pause ad requests after the SDK enables them if the order is not right. If that happens, ads will sometimes not be displayed on a page even if you have consent.

One way to make sure it behaves as expected is to pause requests before the SDK configuration (window.didomiConfig) and before the Didomi and Google <script> tags are embedded in the page.

Google Interactive Media Ads HTML5 SDK (for Video)

When using the Google IMA SDK, you must provide the consent status to your ad tag URL by setting the npa query-string parameter. A value of 0 will display personalized ads and requires consent while a value of 1 will display non-personalized ads and might not require consent.

Google does not offer an API for the Didomi SDK to push that information automatically (like with the GPT or AdSense tag) but you can pass that information from the Didomi SDK API:

window.didomiOnReady = window.didomiOnReady || [];
window.didomiOnReady.push(function (Didomi) {
    // Determine if we should display non-personalized or personalized ads
    var nonPersonalizedAds = 1;
    
    if (!Didomi.isConsentRequired() || Didomi.getUserStatus().vendors.consent.enabled.includes('google')) {
      // No consent required or consent has been given, enable personalized ads
      nonPersonalizedAds = 0;  
    }
    
    // Build the ad tag URL to request personalized ads if possible
    var adTagUrl = 'https://pubads.g.doubleclick.net/gampad/ads?' +
        'sz=640x480&iu=/124319096/external/single_ad_samples&ciu_szs=300x250&' +
        'impl=s&gdfp_req=1&env=vp&output=vast&unviewed_position_start=1&' +
        'cust_params=deployment%3Ddevsite%26sample_ct%3Dlinear&correlator=&npa=' + nonPersonalizedAds; 
    
    // Initialize the IMA SDK and request ads as needed (your existing code)
    var adsRequest = new google.ima.AdsRequest();
    adsRequest.adTagUrl = adTagUrl;
    
    [...]
});

You can read more in the Google IMA SDK documentation on consent.

Ad Manager macros

Didomi can pass the IAB consent string and the GDPR status to Ad Manager as page-level custom targeting variables. These variables can be used in creative snippets with pattern match macros to pass the IAB consent string to creatives/vendors served through Ad Manager creatives.

Configuration

Console

If you manage your consent notices through the Didomi Console, make sure to enable the "Pass IAB consent string and GDPR status as targeting variables to creatives" option for the Google Ad Manager integration.

Tag

If you manage the Didomi tags yourself, set the integrations.vendors.google.passTargetingVariables to true to configure the SDK to pass targeting variables to Ad Manager.

<script type="text/javascript">
window.didomiConfig = {
  app: {
    apiKey: '<Your API key>',
    vendors: {
      iab: {
        include: [
          ..., // All the vendors that you have enabled as ad technology providers in your Google account
        ]
      },
      didomi: [
        // Ask Didomi to collect consent for Google
        'google'
      ]
    }
  },
  
  integrations: {
    vendors: {
      // Setup the integration with Google (ask Didomi to share consent with Google tags)
      google: {
        enable: true,
        eprivacy: true,
        passTargetingVariables: true
      }
    },
  }
};
</script>

Variables

The Didomi SDK pushes the following variables:

Variable name	Description	Macro
iabconsentstring	Current IAB consent string of the user	%%PATTERN:iabconsentstring%%
iabgdprapplies	Whether the GDPR applies to the current user (0 = No / 1 = Yes)	%%PATTERN:iabgdprapplies%%

Macros in creatives

You can use pattern match macros to pass the IAB consent string and GDPR status to a creative.

Example:

The creative code

https://vendor.com/creative?gdpr_consentstring=%%PATTERN:iabconsentstring%%&gdpr_status=%%PATTERN:iabgdprapplies%%

will be rendered as the following code when the creative gets served

https://vendor.com/creative?gdpr_consentstring=SWFtYWNvbnNlbnRzdHJpbmc=gdpr_status=1