WP Consent API

Currently, it is possible for a consent management plugin to block third-party services like Facebook, Google Maps, Twitter, etc. But if a WordPress plugin places a PHP cookie, a consent management plugin cannot prevent this.

Secondly, some plugins integrate the tracking code on the clientside in javascript files that, when blocked, break the site.

Or, if such a plugin’s javascript is minified, causing the URL to be unrecognizable and won’t get detected by an automatic blocking script.

Lastly, the blocking approach requires a list of all types of URL’s that tracks data. A generic API where plugins adhere to can greatly
facilitate a webmaster in getting a site compliant.

Primary this API is aimed at compliant first-party cookies or tracking by WordPress plugins. If such a plugin triggers, for example, Facebook,
usage of this API will be of help. If a user embeds a Facebook iframe, a blocking tool is needed that initially disables the iframe and or scripts.

Third-party scripts have to blocked by blocking functionality in a consent management plugin. To do this in core would be to intrusive, and is also not applicable to all users: only users with visitors from opt-in regions such as the European Union require such a feature. Such a feature also has a risk of breaking things. Additionally, blocking these and showing a nice placeholder requires even more sophisticated code, all of which should in my opinion not be part of WordPress core, for the same reasons.

There are two indicators that together tell if consent is given for a specific consent category, e.g., „marketing“:
1) the region based consent_type, which
can be opt-in, opt-out, or other possible consent_types;
2) and the visitor’s choice: not set, allow, or deny.

The consent_type is a function that wraps a filter, „wp_get_consent_type“. If there’s no consent management plugin to set it, it will return false. This will cause all consent categories to return true, allowing cookies to be set on all categories.

If opt-in is set using this filter, a category will only return true if the value of the visitor’s choice is „allow“.

If the region based consent_type is opt-out, it will return true if the visitor’s choice is not set or is „allow“.

Clientside, a consent management plugin can dynamically manipulate the consent type and set several cookie categories.

A plugin can use a hook to listen for changes or check the value of a given category.

Categories and most other stuff can be extended with a filter.

In addition to category-based consent, the API supports service-level consent control. This allows consent management plugins to grant or deny consent for specific services (like ‚google-analytics‘ or ‚facebook-pixel‘) independently from their category. When checking service consent with wp_has_service_consent(), the API first checks if explicit consent exists for that service. If no explicit consent is set, it falls back to the consent status of the service’s category. This enables fine-grained control: a user might accept statistics cookies in general, but explicitly deny a specific analytics service.

Service consent can be checked and set both server-side (PHP) and client-side (JavaScript):

PHP:

//check if a specific service has consent
if ( wp_has_service_consent( 'google-analytics' ) ) {
    //activate google analytics
}

//check if a service is explicitly denied
if ( wp_is_service_denied( 'facebook-pixel' ) ) {
    //service was explicitly denied by user
}

//set service consent
wp_set_service_consent( 'google-analytics', true ); //grant consent
wp_set_service_consent( 'facebook-pixel', false ); //deny consent

//listen for service consent changes
add_action( 'wp_consent_service_changed', function( $service, $consented ) {
    error_log( "Service {$service} consent changed to: " . ( $consented ? 'granted' : 'denied' ) );
}, 10, 2 );

JavaScript:

//check service consent
if ( wp_has_service_consent( 'youtube' ) ) {
    //activate tracking
}

//check if explicitly denied

if ( wp_is_service_denied( 'facebook-pixel' ) ) {
    //service denied
}

//set service consent

wp_set_service_consent( 'youtube', true );

//listen for service consent changes

document.addEventListener( 'wp_consent_api_status_change_service', function( e ) {
    console.log( 'Service: ' + e.detail.service + ', consented: ' + e.detail.value );
});

Bestehende Integrationen

Kategorisiert und alphabetisch sortiert

wpconsentapi.org
Below are the plugins used to set up the demo site:

//set consent type
window.wp_consent_type = 'optin'

//dispatch event when consent type is defined. This is useful if the region is detected server side, so the consent type is defined later during the pageload
let event = new CustomEvent('wp_consent_type_defined');
document.dispatchEvent( event );

//consent management plugin sets cookie when consent category value changes
wp_set_consent('marketing', 'allow');

javascript, tracking plugin

//listen to consent change event
document.addEventListener("wp_listen_for_consent_change", function (e) {
  var changedConsentCategory = e.detail;
  for (var key in changedConsentCategory) {
    if (changedConsentCategory.hasOwnProperty(key)) {
      if (key === 'marketing' && changedConsentCategory[key] === 'allow') {
        console.log("just given consent, track user")
      }
    }
  }
});

//basic implementation of consent check:
if (wp_has_consent('marketing')){
  activateMarketing();
  console.log("set marketing stuff now!");
} else {
  console.log("No marketing stuff please!");
}

PHP

//declare compliance with consent level API
$plugin = plugin_basename( __FILE__ );
add_filter( "wp_consent_api_registered_{$plugin}", '__return_true' );

/**
* Example how a plugin can register cookies with the consent API
 * These cookies can then be shown on the front-end, to the user, with wp_get_cookie_info()
 */

function my_wordpress_register_cookies(){
    if ( function_exists( 'wp_add_cookie_info' ) ) {
        wp_add_cookie_info( 'AMP_token', 'AMP', 'marketing', __( 'Session' ), __( 'Store a unique User ID.' ) );
    }
}
add_action('plugins_loaded', 'my_wordpress_register_cookies');


if (wp_has_consent('marketing')){
//do marketing stuff
}

Any code suggestions? We’re on GitHub as well!