Developers guide for Third-Party integrations

Upgrade document developers – Complianz 6.0

This document will explain our migration towards a new consent structure, and what you can do as a developer to integrate with Complianz 6.0 and/or change current integrations already developed.

Current Consent Management

Complianz prefers to handle all consent actions with javascript functions and/or hooks. Using PHP has the risk of issues with cached pages, where the PHP is not executed.

There is also a shortcode , which contains the option to redirect with a parameter, fixing any caching issue that might occur.

Since 6.0, several hooks have been renamed or dropped. You can find all dropped or changed hooks in cookiebanner/js/migrate.js. Since 6.0, more info is passed to these hooks, and several new functions have been made available to third parties.

By default, Complianz will activate the complianz migrate.js shipped with the plugin if the plugin was used with a version < 6.0. If a user does not need any of the integrations, or if you have upgraded your integrations, they/you can disable migrate.js in the settings.

New Consent Management

Below you will find the new set-up for Complianz 6.0. It focuses on developing an integration directly in Complianz whereby you can configure a placeholder, detectable service, dependencies and add the desired scripts to a block list that get fired based on the appropriate category.

We recommend not using cookie variables to handle consent. Cookies can have different prefixes (e.g. on multisite root, a cookie may have the cmplz_rt_ prefix). For good measure this the mapping of old and new cookies:

Cookies in use from 6.0 onward

New filters

Data attributes for services requiring consent

In the previous version, services requiring marketing consent got the class “cmplz-script”, and services requiring statistics consent got the class “cmplz-stats”. Scripts that should not get blocked got the class “cmplz-native”.

As of 6.0, this has changed to a data attribute with the category that is required. Additionally, a service can be enabled by service, if the service name is available. This means that the classes are changed as follows:

Some examples:

// Consent Attributes

<iframe data-category=”marketing”
data-service=”youtube”>

<script type=”text/plain” data-category=”statistics”
data-service=”matomo”>

Javascript Functions

console.log( 'Javascript Functions' );

/**
* Check if there is consent for a category or service
* @param string category
* @returns {boolean}
*/

cmplz_has_consent(category)


/**
* Get the status of the banner: dismissed  show
* @returns {string}
*/

cmplz_get_banner_status()


/**
* Set the banner status so it will be either shown or dismissed, and store it in a cookie.
* @param status (optional)
*/

cmplz_set_banner_status(status)


/**
* Check if there is consent for a category or service
* @param category
* @returns {boolean}
*/
cmplz_has_consent(category)

Hooks

console.log( 'Hooks' );

$(document).on("cmplz_enable_category", cmplz_my_custom_hook);
function cmplz_my_custom_hook(consentData) {
  let category = consentData.detail.category;
  let region = consentData.detail.region;
  let acceptedCategories = consentData.detail.categories;

  if (category==='marketing'){
     //do something interesting with marketing consent
  }
}

Most important hooks

console.log( 'Important Hooks' );

// before the banner runs
cmplz_before_cookiebanner

// when a specific category is enabled. passes category, categories, region
cmplz_enable_category

// on a tag manager event. passes the category
cmplz_tag_manager_event

// when the categories are fired. passes category, categories, region
details.region = complianz.region;

// after all scripts have been loaded. passes the category (stats or marketing)
cmplz_run_after_all_scripts

// when the cookie banner is loaded. passes the configuration object from complianz.
cmplz_cookie_banner_data

// when the banner is completely loaded. passes the region.
cmplz_cookie_warning_loaded
// when the status changes. passes category, categories, region
cmplz_status_change

// when revoke is called. passes if a reload is needed or not.
cmplz_revoke

Shortcode

console.log( 'Shortcodes' );

// You can pass in the following parameters:\

'cache_redirect' = false or true
'category' = 'marketing'
'text'     = "Accept marketing cookies to enable this content"

PHP

console.log( 'PHP' );

/**
* @param string $category
*
* @return bool
*/

cmplz_has_consent($category);

5.0 Setting up an integration for Complianz

Using the integrations API is a great way to give your user full control over integrations. When setup this way, the user can see the integration in the integration center, and choose to enable it, or to enable or disable the placeholder (if applicable).

Let’s take for example a Google Maps plugin:

5.1 Declare your integration

1. Add your plugin to the integrations with the cmplz_integrations filter. In this case we use the Mappress constant to detect if the plugin is active. This can also be a function or classname, as long as it’s declared in the core plugin file. If it’s declared too late, it will not be detected anymore.

console.log( 'Declaration' );

/**
* Insert an integration
* @param array $cmplz_integrations_list
*
* @return mixed
*/
function my_plugin_integration($cmplz_integrations_list){
  $cmplz_integrations_list['mappress' ] = array(
        'constant_or_function' => Mappress,
        'label'                => 'MapPress Maps for WordPress',
        'firstparty_marketing' => false,
  );
  return $cmplz_integrations_list;
}
add_filter( 'cmplz_integrations', 'my_plugin_integration');

5.2 Locate your integration

Tell Complianz where this integration file lives. The $plugin variable is the key in the integrations array. In this case mappress. Create a file in your plugin, e.g. complianz.php, and get the path to your plugin folder. Complianz can now load your integration file complianz.php when the integration is enabled. It can also be deactivated from the integrations overview, without having to deactivate either Complianz or your plugin.

console.log( 'Location' );

/**
* @param string $path
* @param string $plugin
*
* @return string
*/
function my_plugin_integration_path($path, $plugin){
  if ( $plugin === 'mappress' ) {
     return 'my_plugin_path/complianz.php';
  }
  return $path;
}
add_filter( 'cmplz_integration_path', 'my_plugin_integration_path', 10, 2 );

5.3 Create the integration

console.log( 'Creation' );

<?php
defined( 'ABSPATH' ) or die ( "you do not have access to this page!" );

To add a script to the integrations array, we add a filter, and push a new array onto the tags array.

Each script URL that should get blocked unless consent is given, should be added to the known script tags array. This can be a part of an inline script, or part of the url to the source. As long as it’s unique.

A URL to be blocked will be added in the ‘urls’ index. In the example below I have added one URL.

The new blocked item should always have a name, category, and at least one url.

console.log( 'Script Blocker' );

/**
* Add a script to the blocked list
* @param array $tags
*
* @return array
*/
function cmplz_mappress_script( $tags ) {
  $tags[] = array(
     'name' => 'mappress',
     'category' => 'marketing',
     'urls' => array(
           'mappress-google-maps-for-wordpress/js/mappress',
     ),
     'enable_placeholder' => '1',
     'placeholder' => 'google-maps',
     'placeholder_class' => 'mapp-canvas-panel',
     'enable_dependency' => '0',
);

  return $tags;
}
add_filter( 'cmplz_known_script_tags', 'cmplz_mappress_script' );

5.3.1 Add a placeholder

We also want to add a placeholder. In the above example we selected an existing one, the “google-maps” placeholder. You can find all possible placeholders in assets/images/placeholders. In this case, the ‘mapp-canvas-panel’ class is used to attach the image to the div. Make sure this is a unique class. As you can see in the snippet above, the ‘enable_placeholder’ value is set to ‘1’, and the class is assigned to the ‘placeholder_class’

You can also declare your own placeholder. This filter will override whatever is in the images/placeholders directory. In the example below, the filter is hooked to the ‘google-maps’ service.

The detected source as well as the suggested new source is passed. You can now pass a completely different one. As Google Maps is already in our assets map, we don’t actually need this function in our Mappress integration.

console.log( 'Placeholder' );

/**
* Declare a placeholder
* @param string $new_src
* @param string $src
*
* @return mixed|string
*/
function cmplz_google_maps_placeholder( $new_src, $src ) {
    //path to custom placeholder
    return $new_src;
}

add_filter( 'cmplz_placeholder_google-maps', 'cmplz_google_maps_placeholder', 10, 2 );

In this case, we need to add some custom css, to make sure the placeholder is displayed correctly:

console.log( 'Custom CSS' );

/**
* Add some custom css for the placeholder
*/
function cmplz_mapppress_css() {
  ?>
     .mapp-main .cmplz-placeholder-element {
        height: 100%;
        width: 100%;
     }
  <?php
}
add_action( 'cmplz_banner_css', 'cmplz_mapppress_css' );

5.3.2 Add the service

The next one is a “nice to have”, not strictly necessary. If you add this filter, the plugin will automatically add “Google Maps” to the list of detected services. See github for the complete list of services, social media and statistics tools that are supported:

https://github.com/complianz/complianz-gdpr/blob/7f078d667efb5ae46c5480fb7fd1fc08f31acb16/config/class-config.php#L14

console.log( 'Add to Complianz' );

// Hook for social media
cmplz_detected_social_media
// Hook for statistics
cmplz_detected_stats_type

/**
* Add services to the list of detected items, so it will get set as default, and will be added to the notice about it
*
* @param $services
*
* @return array
*/
function cmplz_mappress_detected_services( $services ) {

  if ( ! in_array( 'google-maps', $services ) ) {
     $services[] = 'google-maps';
  }

  return $services;
}

add_filter( 'cmplz_detected_services', 'cmplz_mappress_detected_services' );

5.3.3 Dependencies

This one can be a bit complicated. In some cases, the scripts are not loaded in the correct order after the user has consented. That may result in javascript errors like “undefined function” or “undefined constant”.

You can fix that by telling Complianz which script should wait for which other script. In this case, an inline script which contains ‘wpgmp_map’ has to wait for the script containing ‘maps.js’. The maps.js script needs a variable from the inline script, so will break if it’s loaded too early. You can use a part of the url or inline script, but make sure it’s sufficiently unique. In the array we used earlier, wet the ‘enable_dependency’ index to ‘1’, and add an array in ‘dependency’, like this:

console.log( 'Dependency Example' );

In the array we used earlier, set the ‘enable_dependency’
index to ‘1’, and add an array in ‘dependency’,
like this: ['wait-for-this-script'] = 'script-that-should-wait';

console.log( 'Full Integration' );

/**
* Add a script to the blocked list
* @param array $tags
*
* @return array


*/
function cmplz_mappress_script( $tags ) {
  $tags[] = array(
        'name' => 'mappress',
        'category' => 'marketing',
        'placeholder' => 'google-maps',
        'urls' => array(
              'mappress-google-maps-for-wordpress/js/mappress',
        ),
        'enable_placeholder' => '1',
        'placeholder_class' => 'mapp-canvas-panel',
        'enable_dependency' => '1',
        'dependency' => [
              'maps.js' => 'wpgmp_map',
        ],
  );

  return $tags;
}
add_filter( 'cmplz_known_script_tags', 'cmplz_mappress_script' );

If we put this all together, we have a fully functioning integration, manageable from the Complianz integrations dashboard.

You can see the complete Mappress, and other integrations in the Complianz plugin folder, in integrations/plugins. As these are shipped with Complianz already, they don’t contain the foncode to add them to Complianz of course.

Need help? Let us know!