Skip to main content

Preventive block

The purpose of this section is to guide the user on the correct implementation of preventive blocking. Preventive blocking means a feature that allows you to block the insertion of scripts and iframes on the page before the user has expressed their preferences - or given full consent - on the methods of collecting and processing their personal data.

There are two main ways of implementing preventive blocking: manual and automatic through the use of a tag manager. It should be noted that preventive blocking must be implemented for all those vendors who do not adhere to the TCF framework and those who manage (non-technical) profiling cookies.

Integration via plugin on Wordpress

Integrate the plugin on your site via zip through which you will be able to activate the preventive block to ensure that automatic tracking is enabled only after the The user has given consent.

alt_text

To do all this simply tick the last checkbox at the bottom of the page block all scripts in advance. All tracking will be blocked until the user gives consent for it to start.

Blocco preventivo manuale

In order to carry out the preventive blocking, Avacy needs to modify the attributes of all the <script> and <iframe>, of the target vendors, to be blocked preventively according to the following structure:

  • Add the data-managed=as-oil attribute to uniquely identify scripts managed by Avacy
  • Change the value of the type attribute to as-oil so as not to launch the script as it does not recognize its type. This will be converted with the content of data-type once cookies are accepted from the banner.
  • Add the data-type attribute indicating the original type of the script/iframe, in order to maintain the actual type of the script that will subsequently be executed until acceptance of the Cookie Policy
  • Add the data-purposes attribute whose value are the IDs of the purposes that must be activated for the script to run correctly. If this field is omitted, all purposes must be enabled to initialize the element.

Following the previous points you will have a code similar to this:

<script data-managed="as-oil"
        data-type="text/javascript"
        data-src="path/to/the/script.js"
        data-purposes="1,2,4"
        data-custom-vendor="1"
        type="as-oil">
  document.getElementById("demoText").innerHTML = "This text will be shown with given consent!";
</script>
  • Set data-purposes with the 'ids' of the cookie usage purposes required to activate the script (the ids can be found in the list of providers on Avacy or here) . Therefore, during the acceptance phase, if I modify the consent settings, I will only activate the scripts relating to the permitted data-purposes.
  • Set data-iab-vendor with the 'ids' of the IAB vendor if the script you want to block is served by a vendor adhering to the IAB TCF framework, in any other case we use data-custom-vendor. In saas it is possible to check if a supplier adheres to the IAB TCF in the supplier list in the Synchronized column. The list of vendors participating in the IAB framework with their identifiers can be consulted publicly here.

To verify the correct functioning of the preventative block implemented, it is advisable to change the cookie preferences in the second layer of the banner, therefore:

  • to activate the script in the example, you must give consent to purposes 1, 2, 4 and, if specified, a Custom Vendor (or IAB Vendor) by ticking the relevant toggle;
  • to block the script in the example, simply deny consent to one of the purposes indicated (1, 2, 4) or deselect the relevant Custom Vendor (or IAB Vendor)

Furthermore, it is possible, as stated previously, to automate this manual procedure in two ways: LUA or YETT modules.

LUA Modules

On Apache or NGINX web servers it is possible, in general, to intervene on an HTTP response before it is sent to the client, this is possible through the use of LUA modules. In this case it is possible to integrate a LUA module (provided in Avacy) to modify the attributes of the scripts inserted into the page - in a similar way to how it would be done manually - so that it will be served to the browser with the scripts previously blocked. In this case, in the LUA module there is: a blacklist (blacklist.lua) which simply returns a list of URLs to soft-lock; a filter_common.lua script that contains the filtering logic common to Apache and NGINX two scripts filter_httpd.lua and filter_nginx.lua that call the previous script (since each web server provides and expects results differently, some small customization is required)

LUA on NGINX

Enabling the LUA plugin on NGINX can be complex, it is recommended to use NGINX implementations that support it (e.g. openresty), but once done, to activate the script just insert the following lines in the desired context (server/http/location)

header_filter_by_lua_block { ngx.header.content_length = nil }

body_filter_by_lua_file /filter_nginx.lua

Where /filter_nginx.lua is the filesystem path of the file containing the LUA script.

LUA on Apache

To enable LUA on Apache insert (or uncomment) the instruction

LoadModule lua_module modules/mod_lua.so

in the httpd.conf configuration file. To use the script, however, just insert the lines into httpd.conf

LuaOutputFilter OilFilter /httpd_filter.lua OilFilter

SetOutputFilter OilFilter

Where /filter_httpd.lua is the path in the filesystem of the file where the LUA script is contained.

YETT Libraries

An additional parameter is integrated into the configuration object which consists of an array of objects describing regex-consensus pairs. When the page is rendered and you notice a script on the page, if it has a matching with the regex (and is therefore blacklisted), it is blocked by modifying the attributes. The main difference between YETT and LUA is that the YETT library acts client-side.

NOTE: It is important to keep in mind that the scripts to be blocked via YETT must be inserted into the page after the inclusion of the OIL scripts

A first script that is provided has the id avacy-blocking. This script can be inserted inline within the desired page or imported from a directory.

CLIENT_SIDE_BLOCKING = {
    active: true,
    iframes: false,
    blacklist: [
        {
            pattern: /insert-regex-for-blocking/,
            rules: {
                'data-purposes': [1,2,7,9],
                'data-legints':[2, 3, 4, 5, 6, 7, 8, 9, 10],
                'data-special-features': [2],
            }
        },

        // altri pattern da bloccare
        { … }
    ]
}

This script has the task of declaring a global variable (which is therefore included in the window scope), within which there are:

  • a flag to determine whether client-side blocking should be active or not,
  • a blacklist, i.e. an array of objects representing the patterns to be blocked, each object is in turn composed of:
  • a regex that identifies the pattern to check within the script
  • the values ​​of the attributes to be inserted into the script so that they are managed by OIL. They will be arrays containing the ids of the purposes to be checked so that the scripts are activated on the page.

This modification operation is called patching and can be carried out in two different ways, via an observer or via monkeypatch. Both are scripts that are started at different times, the first during the insertion of the <script> intercepts the tag and, if inside the src attribute there is a string that has a match with an element of the blacklist, injects the attributes into the tag and, unless the vendors and purposes required are checked via the banner, blocks the execution of the script. The monkeypatch, however, acts at the DOM level by overriding the document.createElement method, replacing the attributes present in the object with those necessary to pass the blocking management to OIL.

NOTE: Keep in mind that if you have third-party extensions on your browser that modify the document.createElement method, monkeypatch may not work.

How to block specific scripts

If you use preemptive blocking with the Wordpress plugin or frontend blocking, Avacy offers the ability to choose which specific vendor scripts to block.

Enter the supplier list of your web space in the Avacy platform and click on "Other actions" and "Edit quote block URL". In the appropriate space it is possible to insert the text of the script to be blocked.

alt_text

An example of a preventative block on a Facebook Pixel is shown below.

Suppose we have enabled the Facebook provider and have inserted the following snippet into the source code of our site:

<!-- Facebook Pixel Code -->
<script>
  !function(f,b,e,v,n,t,s)
  {if(f.fbq)return;n=f.fbq=function(){n.callMethod?
  n.callMethod.apply(n,arguments):n.queue.push(arguments)};
  if(!f._fbq)f._fbq=n;n.push=n;n.loaded=!0;n.version='2.0';
  n.queue=[];t=b.createElement(e);t.async=!0;
  t.src=v;s=b.getElementsByTagName(e)[0];
  s.parentNode.insertBefore(t,s)}(window, document,'script',
  'https://connect.facebook.net/en_US/fbevents.js');
  fbq('init', '{your-pixel-id-goes-here}');
  fbq('track', 'PageView');
</script>
<noscript>
  <img height="1" width="1" style="display:none" 
       src="https://www.facebook.com/tr?id={your-pixel-id-goes-here}&ev=PageView&noscript=1"/>
</noscript>
<!-- End Facebook Pixel Code -->

By inserting the URL present in the HTML code, or in the src attribute, Avacy will be able to detect the script on the page and automatically patch the attributes as shown in the previous paragraphs. In the example in question, we could write in our text field:

fbevents.js

At that point we save and republish the supplier list. On our site, Avacy will be able to detect the script containing fbevents.js and proactively block it for user consent. Then, inspecting the source, we will notice that the pixel attributes will be overwritten:

<!-- Facebook Pixel Code -->
<script 
    data-managed="as-oil"
    data-type="text/javascript"
    data-purposes="1,2,3,..." <!-- the list of identifiers depends on the purposes selected for the supplier
    data-custom-vendor="{id_vendor}"
    type="as-oil"
  >
  !function(f,b,e,v,n,t,s)
  {if(f.fbq)return;n=f.fbq=function(){n.callMethod?
  // ... the rest of the Facebook Pixel Code...
</script>
<!-- End Facebook Pixel Code -->

⚠️ NOTE: Since it is a free field, it is obviously possible to insert any text into it. It is highly recommended to insert URLs or text that can be uniquely identified within the source, avoiding ambiguity and without running the risk of scripts being identified which, if blocked, could compromise the correct functioning of the site.

Automatic quote blocking with tag manager

Avacy can be easily integrated with some tag management services, this allows you to implement preventive blocking directly through the tag manager, which will then take care of loading a script or an iframe only when a specific event is triggered.

Avacy provides an avacy_consent event in two circumstances: page loading (page_load) or changing and saving banner preferences (consent_update). The event contains details regarding the banner data layers.

Here is an example of the event structure in JSON format before saving the preferences (you can see it by the fact that the optin value is still false):

alt_text

After expressing your preferences (optin becomes true), the JSON will be populated based on the values ​​set in the banner.

To give consent, for example, to a custom vendor, you must tick the toggle relating to that vendor in the appropriate tab and, at the same time, enable all the purposes required by it. If, for example, that vendor requires purposes with id 1, 2 and 3, just tick the relevant toggles in the purpose tab and, when the user gives his consent, the vendor will also be included in the customVendorsWithConsent array, in key-value object format. If only some of the required purposes are enabled (e.g. 1 and 2), the vendor id will only be inserted into the customVendors ID array, but not into customVendorsWithConsent.

This operation is similar for vendors participating in the IAB; the iabVendors and iabVendorsWithConsent arrays will be used in the event.

To handle the event, simply go to your tag management platform and enter the snippet to listen and handle the avacy_consent event. In the following example we can see how to use the Google Tag Manager datalayer.push API to insert the consent event given to some purposes and to some vendors.

<script>
window.addEventListener('avacy_consent', function(event) {  
  console.log('event.detail', event.detail)
  if (event.detail.purposes) {
    event.detail.purposes.forEach(function(element){
        window.dataLayer.push({
          event: 'avacy_consent_given_purpose_' + element
        });
      })
  }
  
  if (event.detail.customVendorsWithConsent) {
    event.detail.customVendorsWithConsent.forEach(function(element){
        window.dataLayer.push({
          event: 'avacy_custom_vendor_' + element.id
        });
      })
  }
  
  if (event.detail.iabVendorsWithConsent) {
    event.detail.iabVendorsWithConsent.forEach(function(element){
        window.dataLayer.push({
          event: 'avacy_iab_vendor_' + element.id
        });
      })
  }
})
</script>

Now, following the example, it is possible to start a certain component (such as Facebook Pixel), based on the fact that the avacy_consent_given_purpose_id event is present in the datalayer (where id is the identifier of the Facebook custom vendor) and, more in general, you can run (or even remove) scripts based on the logic for handling these events.

NOTE: The script is inserted every time the tag manager is called, so it can run even in a sandbox environment and this can cause problems.