Web APIs

APIs to Trigger MSPA Consent Screen

This section outlines the various APIs and callbacks that publishers can use to trigger the MSPA consent screen once they are integrated with GPP.

For more information on APIs that a CMP must support, as specified by IAB, see CMP API Specification.

isUserLocationChanged

This callback aims to know if the user has changed the location and retrigger the MSPA consent screen based on the new location.

Parameters

Example

window.__uspapi(isUserLocationChanged, 1, (result) => {
    console.log(result); // { locationChanged: true, previousLocation: ‘va’, currentLocation: ‘ca’}
});

displayUspUi

This will display the U.S Privacy UI (modal dialog). It will inherit style and style overrides given in the config object.

Example

window.__uspapi('displayUspUi', 1, function(data, status) { console.log(data, status); })

ping

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.

Attributes

Example

__gpp('ping', myFunction);

addEventListener

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.

Attributes

Example

__gpp('addEventListener', (gppData, success) => {
      if (!success) return;
      if (gppData['eventName'] === "signalStatus" && gppData['data'] === "ready" && success) {
        console.log('GPP is ready');
      }
      // To wait for user consent, use below code. Perform actions which are dependent on user consent
      if (gppData['eventName'] === "sectionChange" && gppData['data']) {
        console.log('User consent given/updated:', {
          gppString: gppData['pingData']['gppString'],
          parsedSections: gppData['pingData']['parsedSections'],
          applicableSections: gppData['pingData']['applicableSections'],
        });
      }
    });

removeEventListener

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.

Attributes

Example

__gpp('removeEventListener', myFunction, listenerId);

hasSection

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.

Attributes

Example

A client wants to ask the CMP if there is data for IAB TCF CA v1.0:

__gpp('hasSection', myFunction, "tcfcav1");

getSection

The getSection command can be used to receive the (parsed) representation of a section of a certain specification. The callback shall be called with the (parsed) representation as the argument for the data parameter. The parsed representation of a section is an array of objects, where each object represents one sub-section of this section in the order that is given by the section specification. For example, the data parameter for the TCF Canada will be an array with one or two objects (Core sub-section plus optional publisher purposes sub-section). Each object is composed of the fields defined by the section specification.

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.

Attributes

Example

For example, client can ask the CMP to get the IAB TCF CA v1.0 TCData:

__gpp('getSection', myFunction, "tcfcav1"); 

Example value of data passed to the callback:

[
 /* Core Sub-section */
 {
  Version:1, 
  Created: Date (Thu Apr 13 2023 18:07:12 GMT+0200),
  LastUpdated: Date (Thu Apr 13 2023 18:07:12 GMT+0200),
  CmpId: 31, 
  CmpVersion: 123,
  ConsentScreen: 5,
  ...
  }, 
  /* Publisher Purposes Sub-section (optional) */
 {
  subsectionType:3, 
  PubPurposesExpressConsent : [1,2,3,4,5],
  PubPurposesImpliedConsent  : [6,7,8,9],
  ...
  } 
 ]

getField

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.

Attributes

Example

For example, a client can ask the CMP to get the last updated field from the IAB TCF CA v1.0 TCData.

__gpp('getField', myFunction, "tcfcav1.LastUpdated");