diff --git a/Core/CMP API Specification.md b/Core/CMP API Specification.md index 5e5447c..d92a5ae 100644 --- a/Core/CMP API Specification.md +++ b/Core/CMP API Specification.md @@ -8,9 +8,14 @@ Version Comments + + TBD + 1.1 + Removal of return values in favor of callback functions. Removal of getGPPData command + - TBD -1.0 + Sept 28, 2022 + 1.0 Published final public version @@ -93,24 +98,26 @@ Every consent manager must provide the following API function: Requirements for the interface: -- The function __gpp must always be a function and cannot be any other type, even if only temporarily on initialization – the API must be able to handle calls at all times. +- The __gpp function must always be a function and cannot be any other type, even if only temporarily on initialization – the API must be able to handle calls at all times. - The command must always be a string. -- The callback must be either a function or null. +- The callback must always be a function. - Parameter can be of mixed type depending on used command -- The return value of the function is of mixed type depending on used command +- The __gpp function does not have a return value - If a CMP cannot immediately respond to a query, the CMP must queue all calls to the function and execute them later. The CMP must execute the commands in the same order in which the function was called. -- A CMP must support all generic commands. All generic commands must always be available when a __gpp function is present on the page. This means that “[stub code](#stubcode)” that supports all generic commands must be in place before/during CMP load. +- A CMP must support all generic commands. All generic commands must always be available when a __gpp function is present on the page. This means that “[stub code](#stubcode)” that supports all generic commands must be in place before/during CMP load. + ### What required API commands must a CMP support? -All CMPs must support all generic commands. Generic commands are commands that can be used independent of [section specifications](https://github.com/InteractiveAdvertisingBureau/Global-Privacy-Platform/blob/main/Sections/SectionInformation.md). All generic commands must always be executed immediately without any asynchronous logic and call the supplied callback function immediately. The generic commands are: [‘ping’](#ping), [‘addEventListener’](#addeventlistener), [‘removeEventListener’](#removeeventlistener), [‘hasSection’](#hassection), [‘getSection’](#getsection), [‘getField’](#getfield) and [‘getGPPData’](#getgppdata). +All CMPs must support all generic commands. Generic commands are commands that can be used independent of [section specifications](https://github.com/InteractiveAdvertisingBureau/Global-Privacy-Platform/blob/main/Sections/SectionInformation.md). All generic commands must always be executed immediately without any asynchronous logic and call the supplied callback function immediately. The generic commands are: [‘ping’](#ping), [‘addEventListener’](#addeventlistener), [‘removeEventListener’](#removeeventlistener), [‘hasSection’](#hassection), [‘getSection’](#getsection), and [‘getField’](#getfield). ________ #### `ping` -The `ping` command can be used to determine the state of the CMP. +The `ping` command can be used to determine the state of the CMP. The callback shall be called with a PingReturn object as the value of the `data` parameter. A value of `false` will be passed as the argument to the `success` parameter if the CMP fails to process this command. + @@ -124,21 +131,14 @@ The `ping` command can be used to determine the state of the CMP. - - + + - - - - - - - - +
argument
callbacknot usedfunctionfunction (data: PingReturn, success: boolean)
parameter not used
return PingReturn object
@@ -146,7 +146,7 @@ The `ping` command can be used to determine the state of the CMP. *Example:* ``` javascript -var PingReturn = __gpp('ping');var PingReturn = __gpp('ping'); +__gpp('ping', myFunction); ``` #### `PingReturn` @@ -156,7 +156,7 @@ This object contains information about the loading status and configuration of t ```javascript PingReturn = { -gppVersion : String, // must be “Version.Subversion”, current: “1.0” +gppVersion : String, // must be “Version.Subversion”, current: “1.1” cmpStatus : String, // possible values: stub, loading, loaded, error @@ -166,6 +166,13 @@ supportedAPIs : Array of string, // list of supported APIs (prefix strings), e.g cmpId : Number, // IAB assigned CMP ID, may be 0 during stub/loading +sectionList : Array of Number, // may be empty during loading of the CMP + +applicableSections: Array of Number, // Section ID considered to be in force for this transaction. In most cases, this field should have a single section ID. In rare occasions where such a single section ID can not be determined, the field may contain up to 2 values. During the transition period which ends on July 1, 2023, the legacy USPrivacy section may be determined as applicable along with another US section. In this case, the field may contain up to 3 values where one of the values is 6, representing the legacy USPrivacy section. The value can be 0 or a Section ID specified by the Publisher / Advertiser, during stub / load. When no section is applicable, the value will be -1. + + +gppString: String // the complete encoded GPP string, may be empty during CMP load + } ``` @@ -189,7 +196,7 @@ cmpId : Number, // IAB assigned CMP ID, may be 0 during stub/loading cmpStatus CMP is finished loading - + 'error' cmpStatus CMP is in an error state. A CMP shall not repsond to any other API requests if this cmpStatus is present. A CMP may set this status if, for any reason, it is unable to perform the operation. @@ -217,7 +224,7 @@ cmpId : Number, // IAB assigned CMP ID, may be 0 during stub/loading ___________ #### `addEventListener` -The `addEventListener` command can be used to define a callback function (or a postmessage to respond to for cross-domain case) that can be used to detect changes in the CMP. +The `addEventListener` command can be used to define a callback function that can be used to detect changes in the CMP. The callback shall be called with an `EventListener` object immediately. The GPP script will then call the callback function and return a new EventListener object every time the CMP detects a change (see events below). A value of `false` will be passed as the argument to the `success` parameter if the CMP fails to process this command. @@ -234,20 +241,13 @@ The `addEventListener` command can be used to define a callback function (or a p - + - - - - - - -
callback functionfunction (data: EventListener)function (data: EventListener, success: boolean)
parameter not used
return EventListener object
@@ -255,12 +255,9 @@ The `addEventListener` command can be used to define a callback function (or a p *Example:* ```javascript -var EventListenerReturn = __gpp('addEventListener',myFunction); +__gpp('addEventListener', myFunction); ``` - - -> **Note:** The `addEventListener` command returns an `EventListener` object immediately. The GPP script will then call the callback function and return a new EventListener object every time the CMP detects a change (see events below). - + #### `EventListener` @@ -277,7 +274,7 @@ pingData : object // see PingReturn ``` -A call to the `addEventListener` command must always respond with a return object immediately. When registering new event listeners, the CMP (and stub) must therefore generate new listenerIds for each call to this command. +A call to the `addEventListener` command must always trigger an immediate call to the callback function. When registering new event listeners, the CMP (and stub) must therefore generate new listenerIds for each call to this command. @@ -328,10 +325,10 @@ A call to the `addEventListener` command must always respond with a return objec ______ #### `removeEventListener` -The `removeEventListener` command can be used to remove an existing event listener. +The `removeEventListener` command can be used to remove an existing event listener. The callback shall be called with `false` as the argument for the `data` parameter if the listener could not be removed (e.g. the CMP cannot find a registered listener corresponding to `listenerId`). A value of `false` will be passed as the argument to the `success` parameter if the CMP fails to process this command. -
+
@@ -344,21 +341,14 @@ The `removeEventListener` command can be used to remove an existing event listen - - + + - - - - - - -
argument type
callbacknot usedfunctionfunction (data: boolean, success: boolean)
parameter number ID of the listenerId property that was returned from addEventListener command
return EventListener object
@@ -367,13 +357,13 @@ The `removeEventListener` command can be used to remove an existing event listen *Example:* ```javascript -var EventListenerReturn = __gpp('removeEventListener',null, listenerId); -``` +__gpp('removeEventListener', myFunction, listenerId); +``` __________ #### `hasSection` -The `hasSection` command can be used to detect if the CMP has generated a section of a certain specification. Please note that the command may return `null` when the CMP is not yet loaded. +The `hasSection` command can be used to detect if the CMP has generated a section of a certain specification. The callback shall be called with `true` as the argument for the `data` parameter if the CMP has generated a section for the requested API prefix string. The `data` parameter may be `null` when the CMP is not yet loaded. A value of `false` will be passed as the argument to the `success` parameter if the CMP fails to process this command. @@ -390,38 +380,29 @@ The `hasSection` command can be used to detect if the CMP has generated a sectio callback - not used - + function + function (data: boolean, success: boolean) parameter string API Prefix string - - return - boolean or null - True if the specified section is present, otherwise false - - - - + - - Example: A client wants to ask the CMP if there is data for IAB TCF v2: ```javascript -var b = __gpp('hasSection',null, "tcfeuv2"); +__gpp('hasSection', myFunction, "tcfeuv2"); ``` ______ #### `getSection` -The `getSection` command can be used to receive the (parsed) object representation of a section of a certain specification.
-Please note that this command returns `null` for sections that don't allow accessing the section data object outside an event handler. It may also return `null` when the CMP is not yet loaded. +The `getSection` command can be used to receive the (parsed) object representation of a section of a certain specification. +The callback shall be called with the (parsed) object representation as the argument for the `data` parameter. The `data` parameter may be `null` for sections that don't allow accessing the section data object outside an event handler. It may also be `null` when the CMP is not yet loaded. @@ -438,21 +419,14 @@ Please note that this command returns `null` for sections that don't allow acces callback - not used - + function + function (data: object or null, success: boolean) parameter string API Prefix string - - return - object or null - Section string parsed into an object according to the API specification - - - @@ -461,14 +435,13 @@ For example, client can ask the CMP to get the IAB TCF CA v1.0 TCData: ```javascript -var s = __gpp('getSection', null, "tcfcav1"); +__gpp('getSection', myFunction, "tcfcav1"); ``` A call to ` __gpp('getSection', null, "tcfeuv2");` will return `null`. ______ #### `getField` -The `getField` command can be used to receive a specific field out of a certain section.
-Please note that this command returns `null` for fields in sections that don't allow accessing the section data object outside an event handler. It may also return `null` when the CMP is not yet loaded. +The `getField` command can be used to receive a specific field out of a certain section. The callback shall be called with the value of the requested field as the argument for the `data` parameter. The `data` parameter may be `null` for fields in sections that don't allow accessing the section data object outside an event handler. It may also be `null` when the CMP is not yet loaded. @@ -484,95 +457,22 @@ Please note that this command returns `null` for fields in sections that don't a - - + + - - - - - - -
callbacknot usedfunctionfunction (data: mixed or null, success)
parameter string API Prefix string + "." (dot) + fieldname
returnmixed or nullSection string parsed into an object according to the API specification
-For example, a client can ask the CMP to get the last updated field from the IAB TCF CA v1.0 TCData. +For example, a client can ask the CMP to get the last updated field from the IAB TCF v2.0 TCData. ```javascript -var s = __gpp('getField', null, "tcfcav1.LastUpdated"); -``` -A call to ` __gpp('getField', null, "tcfeuv2.LastUpdated);` will return `null`. - -______ -#### `getGPPData` - -The `getGPPData` command can be used in order to receive the current version of the (encoded) GPP String (e.g. in order to pass it along the supply chain). Please note that the command may return `null` when the CMP is not yet loaded. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
argumenttypevalue
commandstring"getGPPData"
callbacknot used
parameternot used
returnGPPData object or nullParsed header plus the encoded GPP String with all sections representing the current choices.
- - -*Example:* - -```javascript -var s = __gpp('getGPPData'); -``` - -_________ -#### `GPPData` - -The `GPPData` object contains the parsed header section fields, the currently in force section, and the encoded `GPPString` and is defined as follows: - -```javascript -GPPData = { - -sectionId : Number, // Always 3 to indicate the header section - -gppVersion : Number, // The version number parsed from the header - -sectionList : Array of Number, // the sections contained within the encoded GPP string as parsed from the header - -applicableSections: Array of Number, // Section ID considered to be in force for this transaction. In most cases, this field should have a single section ID. In rare occasions where such a single section ID can not be determined, the field may contain up to 2 values. The value can be 0 or a Section ID specified by the Publisher / Advertiser, during stub / load. When no section is applicable, the value will be -1. - -gppString: String // the complete encoded GPP string - -pingData: object // see PingReturn -} +__gpp('getField', myFunction, "tcfeuv2.LastUpdated"); ``` ### What are non-generic commands? @@ -598,7 +498,7 @@ getVendorList Command: iabtcfeuv2.getVendorList -Callback: function(gvl: GlobalVendorList, success: boolean) +Callback: function (gvl: GlobalVendorList, success: boolean) Parameter: (optional) int or string @@ -642,7 +542,7 @@ The key names are a combination of the “IABGPP_” prefix followed by the sect IABGPP_HDR_Version - Integer + String GPP Version @@ -744,7 +644,7 @@ Below are example key names from existing APIs. For a complete list of key names IABGPP_TCFEU2_CmpVersion -IAB TECF EU v2 CMP Version +IAB TCF EU v2 CMP Version IABGPP_TCFEU2_PurposesConsent @@ -874,11 +774,14 @@ window.__gpp_stub = function () if (cmd === 'ping') { return { - gppVersion : '1.0', // must be “Version.Subversion”, current: “1.0” - cmpStatus : 'stub', // possible values: stub, loading, loaded, error - cmpDisplayStatus: 'hidden', // possible values: hidden, visible, disabled - supportedAPIs : ['tcfeuv2', 'tcfcav2', 'uspv1'], // list of supported APIs - cmpId : 31 // IAB assigned CMP ID, may be 0 during stub/loading + gppVersion : '1.1', // must be “Version.Subversion”, current: “1.1” + cmpStatus : 'stub', // possible values: stub, loading, loaded, error + cmpDisplayStatus : 'hidden', // possible values: hidden, visible, disabled + supportedAPIs : ['tcfeuv2', 'tcfcav2', 'uspv1'], // list of supported APIs + cmpId : 31, // IAB assigned CMP ID, may be 0 during stub/loading + sectionList : [], + applicableSections: [-1], //or 0 or ID set by publisher + gppString : '' }; } else if (cmd === 'addEventListener') @@ -896,13 +799,16 @@ window.__gpp_stub = function () eventName : 'listenerRegistered', listenerId: lnr, // Registered ID of the listener data : true, // positive signal -pingData: { - gppVersion : '1.0', - cmpStatus : 'stub', - cmpDisplayStatus: 'hidden', - supportedAPIs : ['tcfeuv2', 'tcfva', 'usnat'], - cmpId : 31 -} + pingData: { + gppVersion : '1.1', + cmpStatus : 'stub', + cmpDisplayStatus : 'hidden', + supportedAPIs : ['tcfeuv2', 'tcfva', 'usnat'], + cmpId : 31, + sectionList : [], + applicableSections: [-1], //or 0 or ID set by publisher + gppString : '' + } }; } else if (cmd === 'removeEventListener') @@ -922,32 +828,17 @@ pingData: { eventName : 'listenerRemoved', listenerId: par, // Registered ID of the listener data : success, // status info -pingData: { - gppVersion : '1.0', - cmpStatus : 'stub', - cmpDisplayStatus: 'hidden', - supportedAPIs : ['tcfeuv2', 'tcfva', 'usnat'], - cmpId : 31 -} + pingData: { + gppVersion : '1.1', + cmpStatus : 'stub', + cmpDisplayStatus : 'hidden', + supportedAPIs : ['tcfeuv2', 'tcfva', 'usnat'], + cmpId : 31, + sectionList : [], + applicableSections: [-1], //or 0 or ID set by publisher + gppString : '' + } }; -} - else if (cmd === 'getGPPData') -{ - //return null; //CMPs can decide to return null during load - return { -sectionId : 3, -gppVersion : 1, -sectionList : [], -applicableSections: [0], /*may be filled by publisher*/ -gppString : '', -pingData: { - gppVersion : '1.0', - cmpStatus : 'stub', - cmpDisplayStatus: 'hidden', - supportedAPIs : ['tcfeuv2', 'tcfva', 'usnat'], - cmpId : 31 -} -}; } //these commands must not be queued but may return null while in stub-mode else if (cmd === 'hasSection' || cmd === 'getSection' || cmd === 'getField') @@ -957,7 +848,7 @@ pingData: { //queue all other commands else { - __cmp.queue.push([].slice.apply(b)); + __gpp.queue.push([].slice.apply(b)); } }; window.__gpp_msghandler = function (event) @@ -978,10 +869,10 @@ var returnMsg = { } }; event.source.postMessage(msgIsString ? JSON.stringify(returnMsg) : returnMsg, '*'); -},'parameter' in i? i.parameter: null, 'version' in i ? i.version : 1); +},'parameter' in i? i.parameter: null, 'version' in i ? i.version : '1.1'); } }; -if (!('__gpp' in window) || (typeof (window.__gpp) !== 'function') +if (!('__gpp' in window) || (typeof (window.__gpp) !== 'function')) { window.__gpp = window.__gpp_stub; window.addEventListener('message', window.__gpp_msghandler, false); @@ -1043,10 +934,10 @@ The sent message shall follow the form outlined below. The command, parameter an ```javascript { __gppCall: { - command: "command", - parameter: “parameter”, - version: 1, - callId: “randomID” + command: 'command', + parameter: 'parameter, + version: '1.1', + callId: 'randomID' } } ```