IAB GPP API

UniConsent CMP supports the Global Privacy Platform (GPP), which allows advertisers, publishers, and technology vendors in the digital advertising industry to comply with regulatory requirements across various markets. The GPP protocol streamlines the transmission of privacy, consent, and consumer choice signals from sites and apps to ad tech providers. The IAB Tech Lab oversees the development of the GPP technical specifications.

You must enable GPP in UniConsent dashboard to use GPP API 1.1.

The IAB Global Privacy Platform (GPP) API

The IAB Global Privacy Platform (GPP) provides several APIs that can be used to retrieve data related to various privacy and consent frameworks. These APIs include:

GPP Data API 1.1:

getGPPData command is removed in GPP API 1.1, you can retrieve the gppData from the response of the ping command. You can only get the response from GPP API with a callback function starting from GPP 1.1. UniConsent still answers getGPPData through a callback for older integrations, but new integrations should use ping or addEventListener.

Organizations and Platforms Utilizing GPP API Version 1.1:

• Google Ad Manager
• Amazon Advertising
• and others

The reliable way to access GPP Consent Data

The reliable method for accessing GPP Consent Data is through an addEventListener callback. This does not require that the CMP tag is loaded or that the GPP API is ready on the page. It is the recommended way to access the current consent status.

__gpp("addEventListener", (data, success) => {
  // the first call only confirms the listener: wait until the consent data is ready
  if (success && data.pingData && data.pingData.signalStatus === 'ready') {
    console.log(data);
    // remove the listener for one time data access
    __gpp('removeEventListener', () => {}, data.listenerId);
  }
});

Ping API:

__gpp("ping", function (data, success) {
  console.log(data);
});

// response

{
  "gppVersion": "1.1",
  "cmpStatus": "loaded",
  "cmpDisplayStatus": "hidden",
  "signalStatus": "ready",
  "supportedAPIs": ["2:tcfeuv2","5:tcfcav1","6:uspv1","7:usnat","8:usca","9:usva","10:usco","11:usut","12:usct","13:usfl","14:usmt","15:usor","16:ustx","17:usde","18:usia","19:usne","20:usnh","21:usnj","22:ustn","23:usmn","24:usmd","25:usin","26:usky","27:usri"],
  "cmpId":68,
  "sectionList":[2,6],
  "applicableSections":[2,6],
  "gppString":"xxxx",
  "parsedSections": {"xxx": "xxx"},
}

Has Section API:

This API checks if a specific section is present within the GPP data object. To check if the IAB EU TCF v2 section is present, the following command can be used:

__gpp("hasSection", function (data, success) {
  console.log(data, success);
}, 'tcfeuv2');

Get Section API:

This API retrieves a specific section within the GPP data object. To retrieve the IAB EU TCF v2 section, the following command can be used:

__gpp("getSection", function (data, success) {
  console.log(data, success);
}, 'tcfeuv2');

Get Field API:

This API retrieves a specific field within a section of the GPP data object. To retrieve a list of Vendor IDs with consent given for the IAB EU TCF v2, the following commands can be used:

__gpp("getField", function (data, success) {
  console.log(data, success);
}, 'tcfeuv2.VendorConsents');

US National and State Sections

For US visitors, UniConsent sends the US National section (usnat) and, for states with their own GPP section, the state section: California (usca), Virginia (usva), Colorado (usco), Utah (usut), Connecticut (usct), Florida (usfl), Montana (usmt), Oregon (usor), Texas (ustx), Delaware (usde), Iowa (usia), Nebraska (usne), New Hampshire (usnh), New Jersey (usnj), Tennessee (ustn), Minnesota (usmn), Maryland (usmd), Indiana (usin), Kentucky (usky) and Rhode Island (usri).

Use the section names above with hasSection, getSection and getField. Older names such as usnatv1 or uscav1 are not part of the GPP specification and return no data.

__gpp("getField", function (data, success) {
  console.log(data, success); // 1 = opted out, 2 = did not opt out
}, 'usnat.SaleOptOut');

When a US visitor's browser sends a Global Privacy Control (GPC) signal, UniConsent records an opt-out of sale, sharing and targeted advertising and sets Gpc to true in the sections that have it, without any action from the visitor. This also applies when no US privacy option is enabled. In that case the site's tags still load and analytics stays on: only personalised advertising stops (Google Consent Mode ad_user_data and ad_personalization are denied). If the visitor later saves a choice in the banner, that choice takes precedence over GPC. On consent categories banners, GPC turns off the Targeting or Advertising category until the visitor saves a choice. GPC does not change IAB TCF consent for the EU or Canada.

Choose the states, the GPP sections and your MSPA status in the UniConsent dashboard under US State Privacy and GPP.

When only CCPA is enabled, UniConsent sends the US Privacy section (uspv1) together with usnat and, for California visitors, usca, all with the same CCPA choice. IAB deprecated the US Privacy string in January 2024, so GPP readers can use usnat and usca, while uspv1 and __uspapi remain for older partners.

Common Stub Code Error

Uncaught TypeError: p is not a function
    at window.__gpp_stub (stub.min.js:3:519)

You can only get the response from GPP API with a callback function starting from GPP 1.1. Upgrade your API to use GPP 1.1 API.

GPP Data API 1.0 (Deprecated)

This API allows for the retrieval of the entire GPP data object, which includes data for all supported regulatory frameworks. GPP 1.0 commands returned the result directly. UniConsent now answers getGPPData only through a callback:

__gpp('getGPPData', function (data, success) {
  console.log(data);
});

The GPP 1.0 forms below pass null instead of a callback and no longer return data. Use the GPP 1.1 forms above.

Has Section API:

This API checks if a specific section is present within the GPP data object. To check if the IAB EU TCF v2 section is present, the following command can be used:

__gpp('hasSection', null, 'tcfeuv2')

Get Section API:

This API retrieves a specific section within the GPP data object. To retrieve the IAB EU TCF v2 section, the following command can be used:

__gpp('getSection', null, 'tcfeuv2')

Get Field API:

This API retrieves a specific field within a section of the GPP data object. To retrieve a list of Vendor IDs with consent given for the IAB EU TCF v2, the following commands can be used:

__gpp('getField', null, 'tcfeuv2.VendorConsents')
__gpp('getField', null, 'tcfeuv2.VendorLegitimateInterests')

These APIs allow for the retrieval of important data related to various privacy and consent frameworks, which can be used by advertisers, publishers and technology vendors in the digital advertising industry to adapt to regulatory demands across markets. The IAB Tech Lab stewards the development of these technical specifications.

Compare GPP with IAB TCF 2.3 API

The Global Privacy Platform (GPP) API and the IAB TCF EU v2 API both serve the purpose of enabling compliance with the EU TCF framework. However, they differ in the following ways:

1. Scope: The GPP API is a single protocol designed to streamline transmitting privacy, consent, and consumer choice signals from sites and apps to ad tech providers globally. On the other hand, the IAB TCF EU v2 API is specifically designed for transmitting signals related to the EU TCF framework.

2. Stewardship: The GPP protocol is overseen by the IAB Tech Lab, which also stewards the IAB TCF EU v2 API. However, the GPP protocol encompasses other technical specifications beyond the EU TCF, while the IAB TCF EU v2 API is solely focused on the EU TCF.

3. Functionality: The GPP API provides a range of functions beyond the EU TCF, such as retrieving CCPA data, while the IAB TCF EU v2 API focuses solely on retrieving data related to the EU TCF framework.

4. Syntax: The GPP API and the IAB TCF EU v2 API have different syntax for retrieving data. For example, to retrieve the EU TCF v2 section within GPP data, the following command is used:

__gpp("getSection", function (data, success) {
  // Code to handle response
}, "tcfeuv2")

Whereas, to retrieve the same data using the IAB TCF EU v2 API, the following command is used:

__tcfapi('getTCData', 2, function (tcData, success) {
  // Code to handle response
})

While both the GPP API and the IAB TCF EU v2 API serve the purpose of enabling compliance with the EU TCF framework, the GPP API is a more comprehensive protocol designed to streamline transmitting privacy, consent, and consumer choice signals globally, while the IAB TCF EU v2 API is specifically designed for transmitting signals related to the EU TCF framework.