Implementing Oath s CMP JS

Size: px

Start display at page:

Download "Implementing Oath s CMP JS"

Ross Lynch
5 years ago
Views:

1 Implementing Oath s CMP JS A Guide For Third Party Publishers - V1.1 Table of contents Implementing Oath s CMP JS A Guide For Third Party Publishers - V What s new in this version? What is CMP JS? P Publisher integration and initialisation of CMP JS Consent UI CMP JS configuration for consent UI Modal iframe integration Standalone UI integration Vendor List API Publisher hosted vendor list API 8(9) Oath hosted vendor list API Reprompting for consent Ad Call/Pixel Integration of CMP JS Checking for the existence of CMP JS Same frame integration Iframe integration safeframe integration Frequently Asked Questions Appendix Removed sections Multi-domain support (only supported for direct pub relationships!) For more information, contact your Oath representative Oath Inc. All rights reserved 1

2 What s new in this version? V1.1 of this integration guide contains: An updated cmp3p.js stub tag Updated script in the Iframe Integration section Added details for publisher hosted vendor list API Added details for reprompting for user consent Added link to CMP consent UI reference implementation on GitHub VERSION DATE UPDATES 1.0 4/19/2018 Issued /1/2018 Updated CMP Stub Tag Updated script in the IFrame Integration section Added details for publisher hosted vendor list API Added details for reprompting for user consent Added link to CMP consent UI reference implementation Removed support for a default consent UI hosted by Oath Oath Inc. All rights reserved 2

To comply with the European Union s General Data Protection Regulation (GDPR) we collect and present the vendor information in a standardised format sanctioned and developed by the IAB.

3 What is CMP JS? Oath s CMP JS is a client-side JavaScript interface. It facilitates the requesting, storage and sharing of information about vendors and their approved consent to allow their data to be gathered, mined, and used. To comply with the European Union s General Data Protection Regulation (GDPR) we collect and present the vendor information in a standardised format sanctioned and developed by the IAB. Detailed information on the IAB CMP JS API v1.1 spec can be found here. Publishers should implement the integration instructions described in the 3P Publisher integration and initialisation of CMP JS section. Consumers of consent data (ad calls, pixel calls, etc) should implement the integration instructions described in the Ad call/pixel integration of CMP JS. Oath Inc. All rights reserved 3

4 3P Publisher integration and initialisation of CMP JS There are two steps that must be taken. 1 Add the following tags to your pages. The first tag is a stubbed version of CMP JS which will queue up any CMP JS requests. The queued requests will be executed once CMP JS has finished loading. This tag should be included in the page header above any script tags that would need to access the CMP. Both an unminified version and a minified version of this tag are listed below.  <script type="text/javascript"> (function () { var gdprappliesglobally = false; function addframe() { if (!window.frames[' cmplocator']) { if (document.body && document.body.firstchild) { var body = document.body, iframe = document.createelement('iframe'); iframe.style.display = 'none'; iframe.height = iframe.width = 0; addframe(); iframe.name = ' cmplocator'; body.insertbefore(iframe, body.firstchild); else { settimeout(addframe, 5); function stubcmp() { var b = arguments; cmp.a = cmp.a []; if (!b.length) return cmp.a; else if (b[0] === 'ping') { b[2]({ "gdprappliesglobally": gdprappliesglobally, "cmploaded": false, true); else { cmp.a.push([].slice.apply(b)); Oath Inc. All rights reserved 4

5 function cmpmsghandler(event) { var msgisstring = typeof event.data === "string"; var json = event.data; if (msgisstring) { try { json = JSON.parse(event.data); catch (e) { if (json. cmpcall) { var i = json. cmpcall; window. cmp(i.command, i.parameter, function (retvalue, success) { var returnmsg = { " cmpreturn": { "returnvalue": retvalue, "success": success, "callid": i.callid ; event.source.postmessage(msgisstring? JSON.stringify(returnMsg) : returnmsg, '*'); ); if (typeof ( cmp)!== 'function') { window. cmp = stubcmp; cmp.msghandler = cmpmsghandler; if (window.addeventlistener) window.addeventlistener('message', cmpmsghandler, false); else window.attachevent('onmessage', cmpmsghandler); )(); </script>   <script type="text/javascript">!function(){var e=!1;function a(e){var a="string"==typeof e.data,t=e.data;if(a)try{t=json.parse(e.data)catch(e){if(t. cmpcall){var n=t. cmpcall;window. cmp(n.command,n.parameter,function(t,c){var i={ cmpreturn:{returnvalue:t,success:c,callid:n.callid;e.source.postmessag e(a?json.stringify(i):i,"*"))!function e(){if(!window.frames. cmplocator)if(document.body&&document.body.firstchild ){var a=document.body,t=document.createelement("iframe");t.style.display="none",t.h eight=t.width=0,t.name=" cmplocator",a.insertbefore(t,a.firstchild)else settimeout(e,5)(),"function"!=typeof cmp&&(window. cmp=function(){var a=arguments;if( cmp.a= cmp.a [],!a.length)return cmp.a;"ping"===a[0]?a[2]({gdprappliesglobally:e,cmploaded:!1,!0): cmp.a.p ush([].slice.apply(a)), cmp.msghandler=a,window.addeventlistener?window.add EventListener("message",a,!1):window.attachEvent("onmessage",a))();</script>  Oath Inc. All rights reserved 5

6 The second tag loads the CMP JS script asynchronously to mitigate any performance impact to the page load time. This tag can be included anywhere on the page after the stub tag, but it is recommended that this tag be included early in the page to avoid impacting initial ad load time. Note that IE does not support the async attribute and therefore loads the script synchronously. To avoid this, you may choose to include this script at the end of the page or via javascript.  <script type="text/javascript" src=" async></script> 2 Initialize CMP JS by calling the init method <script type="text/javascript"> /** * Triggers the trap logic, and initializes CMP for * other scripts (such as ad calls) to access consent data * * The config object format for 3rd party publishers * { * gdprappliesglobally: boolean - true for EU targeted sites * pubvendorlistapi: string - full API URL for the publisher hosted * vendor list API * pubvendorlistversionapi: string - full API URL for the publisher hosted * latest vendor list version API * customconsentui: { * url: string - URL to publisher's consent UI * displayinmodal: boolean - true (default) if consent UI should * be rendered in a modal iframe * false if consent UI should be rendered as standalone page * customparams: object - used for providing any publisher specific * parameters to the consent UI * * * {object config */ window. cmp('init', config); </script> Oath Inc. All rights reserved 6

7 Consent UI You can easily integrate your CMP consent UI with Oath s CMP. The consent UI is responsible for capturing user consent. Once captured, the consent is passed to the CMP. The consent UI can be integrated as an iframe rendered in a modal directly on the site, or as a standalone page that the CMP would redirect to. Oath has implemented a reference implementation of the CMP consent UI. It is available on Github at CMP JS configuration for consent UI The following is a sample initialization with your own consent UI where consent.cmp.publisher.com refers to your hosted consent capture flow initialized as a modal on. window. cmp('init', { customconsentui: { url: 'consent.cmp.publisher.com', displayinmodal: true, customparams: {,... ); Modal iframe integration When the CMP requires the user to provide consent, it will load the publisher provided config.customconsentui.url in an iframe. It will then post a message to the iframe with the following message format. cmpuicall: { command: 'renderconsentui', parameter: customparams, // this is the config.customconsentui.customparams object passed into the init call. callid: uniqueid Oath Inc. All rights reserved 7

8 The consent UI should listen for this message, then initialize the UI. Once the user has saved their consent, the consent UI should post a message back to the parent window with the following format. cmpuireturn: { returnvalue: consentstring, // bsee64 encoded consent string success: boolean, // true if success was captured, false if some error occurred. callid: uniqueid // same uniqueid passed in the cmpuicall message Once the CMP receives the cmpuireturn message, it will destroy the iframe. Standalone UI integration (using redirects) When the CMP requires the user to provide consent, it will redirect to config.customconsentui.url with a redirect_url query parameter. Once the user has saved their consent, the UI should redirect back to the redirect_url passing an EuConsent query parameter with the value of the base64 consent string. Vendor List API As part of the user experience for collecting consent under GDPR, a user should be able to select the vendors a publisher works with who they consent to share their data with. Each publisher should provide their own list of vendors with which they share data. The vendor list information is used by both the publisher s CMP consent UI and the CMP JS. To enable this support, publishers have 2 options. 1 Publishers may host an API that would be called by both the publisher s CMP UI as well as the Oath CMP JS. 2 Publishers may provide their vendor list to Oath and utilize Oath s hosted CMP Service API for managing the vendor list. Oath Inc. All rights reserved 8

9 Publisher hosted vendor list API The benefit of publishers hosting their own vendor list API is that it makes it easier for them to manage their vendor list independently. The API should include 2 endpoints. One to provide the vendor list. The other to provide the latest vendor list version. Vendor List API This API enables the client to retrieve the publisher vendor list. API path - The recommended API path is [domain]/cmp/v0/vendor_list, but there is no requirement for this format. version query parameter - This optional query parameter should be supported. If specified, the API should return the requested version. Otherwise, the response should contain the latest vendor list. If an invalid version is specified, the API should respond with a 404 status code. Response format - The response format is as defined by the IAB, with the addition of 1 property. The IAB spec for the vendor list format can be found here. As defined by the IAB spec, the vendor list response object should include the following properties. vendorlistversion - version of the global vendor list used to generate the publisher vendor list lastupdated - date/time when the publisher vendor list was updated purposes - list of purposes any of the publisher s vendors may use the data for vendors - list of vendors the publisher shares user data with The additional required property is publishervendorlistversion - a version number for this publisher vendor list. This should be an number starting at 0 and incremented by 1 with each updated list. Latest Vendor List Version API This API provides the version number of the latest vendor list. This is used by the CMP JS to determine when to reprompt the user for consent. New versions typically mean new vendors have been added and require consent. API path - The recommended API path is [domain]/cmp/v0/vendor_list/latestversion, but there is no requirement for this format. Response format - The response format is an object with a version property set to the publishervendorlistversion of the latest publisher vendor list. For example, { version : 3. Oath Inc. All rights reserved 9

10 Integrating publisher hosted APIs with CMP JS The CMP JS needs to be configured to reference both of these APIs. This is done in the config passed to the cmp( init, config) command when initializing the CMP. See the section above on initializing the CMP for details on this configuration. Oath hosted vendor list API Publishers may choose to utilize Oath s CMP Service API to host their vendor list. To enable this, publishers would follow a process for providing their vendor list (and updates to the list) to Oath. For additional information on this process, please contact your Oath representative. Reprompting for consent For compliance with EU law and IAB policies, users must have an opportunity to modify or revoke their consents. The CMP JS supports this with a command called renderconsents. To reprompt the user, call the following command. window. cmp( renderconsents, callback); The callback argument is optional. If provided, 2 arguments will be passed to the callback function after the user has updated their consent preferences. The callback function signature is shown below, where consentstring is the base64 encoded IAB consent string and success is a boolean specifying whether the consent capture flow was completed successfully. Function callback(consentstring, success) { Oath Inc. All rights reserved 10

11 Ad Call/Pixel Integration of CMP JS This section describes how you or your partners who wish to read consent from the CMP can query the CMP API to get consent parameters. Any partners running on your sites who support the Transparency & Consent Framework can check consent using the JS API. This may also be helpful if you work with partners who cannot read consent automatically from the CMP JS. In this case, you may need to read the consent parameters directly so that you can populate those into your partner tags. Checking for the existence of CMP.js If your code is always in the same frame as CMP JS, you can check for the presence of a function named cmp. For code that may be running in an iframe, sample code is provided in the iframe integration section below for locating the frame containing CMP JS. Same frame integration 1. Retrieve the consent information by calling the getconsentdata method 2. Append consent string and EU jurisdiction flag in ad / pixel calls window. cmp('getconsentdata', null, function (result) { // consentdata contains the base64-encoded consent string var consentdata = result.consentdata; // gdprapplies specifies whether the user is in EU jurisdiction var gdprapplies = result.gdprapplies; ); // pass these 2 values to all ad / pixel calls Oath Inc. All rights reserved 11

12 Iframe integration 1. Retrieve the consent information by posting a message to the parent frame 2. Append consent string and EU jurisdiction flag in ad / pixel calls The postmessage() function can be used from an iframe to send calls to a parent's (or ancestor's) frame s cmp() function. The frame to send the postmessage to can be determined by the ancestor with a.frames[" cmplocator"] child iframe present. CMP tags will install an event handler to call cmp() for postmessage events, returning the data via a postmessage event. This is included as part of the CMP stub tag, so that postmessage events can be handled as early as possible. Below is a wrapper function that emulates the same frame cmp() call. It locates the ancestor frame running the CMP, performs the postmessage and listens for the return message and passes its values to the callback: // (updated T08:00) if (!window. cmp) { // find the CMP frame var f = window; var cmpframe; while (!cmpframe) { try { if (f.frames[" cmplocator"]) cmpframe = f; catch (e) { if (f === window.top) break; f = f.parent; var cmpcallbacks = {; /* Set up a cmp function to do the postmessage and stash the callback. This function behaves (from the caller's perspective) identically to the same frame cmp call */ window. cmp = function (cmd, arg, callback) { if (!cmpframe) { callback({msg: "CMP not found", false); return; var callid = Math.random() + ""; var msg = { cmpcall: { command: cmd, parameter: arg, callid: callid ; Oath Inc. All rights reserved 12

13 cmpcallbacks[callid] = callback; cmpframe.postmessage(msg, '*'); /* when we get the return message, call the stashed callback */ window.addeventlistener("message", function (event) { var msgisstring = typeof event.data === "string"; var json = event.data; if (msgisstring) { try { json = JSON.parse(event.data); catch (e) { if (json. cmpreturn) { var i = json. cmpreturn; cmpcallbacks[i.callid](i.returnvalue, i.success); delete cmpcallbacks[i.callid];, false); /* example call of the above cmp wrapper function */ window. cmp('getconsentdata', null, function (result, success) { if (success) { // consentdata contains the base64-encoded consent string var consentdata = result.consentdata; ); // gdprapplies specifies whether the user is in EU jurisdiction var gdprapplies = result.gdprapplies; // pass these 2 values to all ad / pixel calls else { // either CMP is not on the publisher's page or an error occurred. safeframe integration Information on accessing the CMP from within a safeframe can be found in the IAB CMP JS API spec here. Oath Inc. All rights reserved 13

14 Frequently Asked Questions Do I need to host the CMP JS script on my site domain? No, as long as the CMP JS script loads in the 1st-party domain, the CMP will be able to store consent as a 1stparty cookie. For server to server ad calls that take place before content is returned to the browser, do I need to add CMP JS to my pages? For more information, please contact your Oath representative. Yes, include CMP JS because occasional downstream creatives and pixels may need to obtain consent. However, if you are confident your property only conducts S2S ad calls you may opt out. My buyers sometimes provide HTML-based creatives which initiate third-party integrations, some of which will now need access to the consent parameters I would pass. Could these third parties use JavaScript to retrieve consent parameters within a creative? Yes. The interface is standardised so that any client-side component that ingests and interprets consent can get this from the CMP JS. How does CMP JS work with creatives inserted into iframes? The IAB spec specifies iframe communication to and from the CMP JS be allowed via postmessage()/safeframes. See the example above in the Ad Call/Pixel integration section. Oath Inc. All rights reserved 14

Transparency & Consent Framework

Transparency & Consent Framework Consent Manager Provider JS API v1.0 Table of Contents Introduction... 2 About the Transparency & Consent Framework... 2 About the Transparency & Consent Standard... 3