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
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.didomiproperty)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.
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 userStatus = Didomi.getCurrentUserStatus();
if (
userStatus.vendors.hasOwnProperty("google") &&
userStatus.vendors["google"].enabled
) {
// 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. Additionally, you must set the fullATP field to false:
<script type="text/javascript">
window.didomiConfig = {
app: {
vendors: {
iab: {
version: 2
},
didomi: ['google'],
google: {
fullATP: false
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 
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
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.
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.
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;
const userStatus = Didomi.getCurrentUserStatus();
if (
!Didomi.isConsentRequired() ||
(userStatus.vendors.hasOwnProperty("google") &&
userStatus.vendors["google"].enabled)
) {
// 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:
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=1Last updated