Configuration
0. Overview
As the Klaro configuration can become quite extensive, we have sorted the individual components into different configuration areas. This makes the configuration clearer and helps you find the parameters faster. This means that the parameters of the KlaroConfig file are now found in four areas.
These four areas are:
- Klaro configuration (config)
- Klaro services (config.services)
- Klaro purposes (purposes)
- Klaro translations (config.translations)
Klaro quick configuration
Several questions showed us that the configuration of Klaro is not as easy as it ideally should be. That is why this documentation starts with a quick configuration section. With it you should be able to create a working configuration within about 5 minutes after installing the bundle. The following three steps are required: 1. Create a configuration 2. Create two translations and 3. Assign the configuration to the website root (root page).
1. Create a minimal configuration
2. Create two translations
To start, Klaro needs the translation for the current language (here we assume de) and a
fallback language, which Klaro calls zz. The screenshot shows two suggestions for naming them.
Now create, for example, a German translation named Deutsch-Deutschland (de-DE) with the language code
de, and a second fallback translation named Klaro Default (zz-ZZ) (or Klaro Fallback (zz-ZZ))
with the language code zz. You can ignore the two warnings here.
3. Assign the configuration to the website root
Once that is done, switch to the root page (we assume a root page already exists)
and activate the Klaro configuration you just created.
You recognize the root page by the type Website root. Only this page type has the option
Klaro settings. Activate your Klaro configuration here and assign it to the website root.
Done
If you now reload the page in the front end, you should see the Klaro Consent Manager at the bottom right.
It looks like this:
As no purposes and services have been configured yet, the modal dialog with the services stays empty after clicking
Let me choose. Configuring services and purposes would therefore be the next step.
We recommend defining purposes first and then creating services. Basic purposes would be: analytics, statistics, video-streaming, audio-streaming, security etc. Basic services would be: google-analytics => analytics (purpose), matomo => statistics, youtube-video => video-streaming, vimeo => video-streaming, soundcloud => audio-streaming etc.
Configuring Klaro (in detail)
The Contao Klaro module makes the Klaro configuration more flexible, because the KlaroConfig is always rebuilt from the parameter set at runtime. This makes changes to the configuration quick and easy. This concept also allows you to keep many configurations, which can be assigned to a website root (root page) as needed. There can, however, only be one valid configuration per root page. This way you can define different privacy profiles for your site and activate the right one when needed. The module respects the language code of the website root (root page), so nothing else needs to be configured here. Of course you still have to define a translation, otherwise Klaro only shows the default language.
Where do I start?
If you want to use Klaro on your site, we recommend that you first check your site structure and adjust it if necessary. Perhaps your site already follows the recommendations described below?
For multilingual sites there should be a website root (root page) for each language (see screenshot).
Below each of these website roots there should be a page with the language-specific privacy policy.
You can select this page later in the configuration to link in a friendly way to the
privacy policy in the respective language.
A small detour…
Once this structure exists, you could simply open and edit the desired website root under Site structure.
There you find (but only if it is a website root, a so-called root page)
the additional legend Klaro settings.
A Klaro configuration is always bound to the root page (website root) of a website!
1. Klaro configuration
You manage the Klaro configurations in the menu Klaro configuration. Each configuration offers the
options below. We explain them one after the other…
Basic settings
In the basic settings you can give the configuration a name. As mentioned at the beginning,
Contao Klaro supports many configurations, of which Klaro only uses one at runtime.
As there can be many configurations, you have to give each one a name.
Configure services
Here you configure the services that Klaro should manage. Klaro can manage any number of (custom) services. Each service is categorized. The category is the purpose of the service. The concept is perhaps easiest to explain with the two components Klaro notice (sometimes also called consent box) and Klaro manager (also called modal window). Here comes another small detour…
Klaro essentially appears on your website through two visible elements: the Klaro notice
(consent box) and the Klaro manager (modal window). The Klaro notice is shown to visitors every time
they open the website, as long as Klaro does not find any consent information in its storage.
The Klaro notice looks like this:
The Klaro manager is shown to visitors when they click the link ‘Let me choose’. It
can also be opened explicitly via the API with klaro.show().
The Klaro manager lists the purposes (categories) one below the other, and each purpose can have one or
more services assigned. It looks roughly like this…
Purposes can be, for example: Analytics, Security, Chat, Advertising or Streaming – etc.
You can define the purposes yourself.
By services, Klaro basically means the websites (or API endpoints) to which user data requiring consent
is transferred. You can also define the services yourself.
Users are therefore asked for their consent to a service or a purpose.
A purpose can be assigned to many services and a service to many purposes. You define these assignments yourself.
After this short definition of the terms purpose and service, let’s continue with the configuration.
We had stopped at the services. The services that a configuration should use can be selected
in the following section. Here is an example:
When you configure Klaro for the first time, you will probably not see any services to choose from here. You have to define your services first before you can complete the configuration. You can read more about configuring services under 2. Configure Klaro services.
Configure the script
You can skip this point. It is only relevant for experienced users!
Klaro is written in JavaScript. Here you can define two parameters for the script itself. The first parameter is the loading mode and the second the name of the configuration variable.
The loading mode defines how the script is loaded. The way it is loaded is not unimportant, but we won’t go into detail here. Klaro supports the modes synchronous, deferred (defer) and asynchronous (async). The mode defer is recommended. It is the default.
You can define a different name for the configuration variable here. This is usually not necessary. If, however,
a variable with the same name happens to exist in the current namespace, a different
name may be necessary.
Configure the consent notice
When the page loads and the consent box is shown at the bottom right, you can set some parameters for this display. Another short note first:
Klaro usually does not start with the Klaro manager (modal window), but only with the consent box,
a small notice at the bottom right of the browser window. It looks (roughly) like this:
The text shown here, ‘Consent Notice Text 4096 Zeichen und HTML Text’, is just an example text that you can
define yourself; we explain it in more detail later.
The following parameters can be configured:
The first switch, HTML mode, lets you output HTML instead of plain text as the notice. This opens up
many more possibilities for designing notice texts in Klaro. Even tables and graphics can
be displayed. In theory even SVG would be possible, but we haven’t tried it yet…
The switch Start Klaro as a modal dialog shows the Klaro manager immediately on start instead of the consent box. The Klaro manager overlays the website content so that the visitor can change their consents. Clicking outside the modal window closes the manager without applying the changes. Only after clicking Save is the consent information stored locally (see also the next section Configure cookies).
The switch Force modal means that the Klaro manager cannot be closed until the user has explicitly confirmed with Save. This lets you require certain consents before the site can be used, because the site cannot be used while the Klaro manager is open as a modal.
The switch Default consent for all services is self-explanatory. If enabled, all services are set to accepted when Klaro starts or on the first visit to the site. The Klaro developers advise against using it, as it contradicts the concept of self-determined privacy.
The switch Accept all shows an additional button in the Klaro manager that lets the user accept all services with one click. If this option is not enabled, each service has to be accepted individually.
If the option Hide »I decline« is enabled, the corresponding button in the Klaro notice is hidden. As a result, the user has to open the manager to withdraw consent. The Klaro developers advise against using it, as it contradicts the concept of self-determined privacy.
If the option Hide »Let me choose« is enabled, the corresponding button in the consent box (notice) is affected. This button lets website users open the manager and configure their consents individually.
The last option in this section lets you select pages in your page tree on which the Klaro manager and the Klaro notice should not be active. Klaro.js itself is still loaded on all pages. This is necessary so that the manager can be opened again to change the consents.
Configure cookies
In this section you configure the storage behavior of Klaro. Another
configuration option for cookies is in the section
Cookie rules of the services.
There you can define a separate list of cookie rules for each service.
The following parameters can be configured:
The DIV ID is the »ID« attribute of the Klaro DIV tag. Strictly speaking, this is not a parameter related to storage behavior. You can simply define your own ID here if the default one is already in use. The default is ‘klaro’.
Under Storage key you can change the key for the browser local storage. Klaro writes the consent information to a storage on the client side (see also the following parameter). To find this information again, Klaro needs an identifier. That is this storage key. It has nothing to do with encryption. The default is ‘klaro’.
Under Storage method you choose in which storage Klaro.js saves the consent information. Klaro currently offers the two options Cookie Storage and Browser Local Storage. Feel free to look up the pros and cons of these two storage locations. The default is Cookie Storage.
In the field Cookie domain you configure the domain. Don’t forget this! Without the domain your root page is running on, Klaro does not work correctly. So please configure the cookie domain!
Finally, you can set the cookie expiry time here. The default is 30 (days).
Callback definition
You can skip this point. It is only relevant for experienced users!
Klaro.js supports callbacks (rudimentarily). Basically two callback definitions are possible (not to be confused with the watchers briefly mentioned in the Klaro API!). One callback can be defined in the KlaroConfig and one more for each service. As the KlaroConfig can define several services, there can be many service callbacks, but only a single config.callback. The callbacks have a uniform signature of the form function(consent,service) {}, where consent (bool = true/false) is the consent status and service represents the internal Klaro service object. consent returns the current consent status for the given service. You cannot change the function signature in the Contao Klaro module, only write the function body yourself. You are responsible for correct script code!
We were not successful in finding a useful application for the callbacks. At least they do not behave as described in the annotated configuration. However, we didn’t spend much time analyzing the Klaro code, as that was not our goal. You find a small overview of the problems on GitHub
Testing and maintenance
Here you can activate a so-called test mode. You find a short note on it in the annotated config.
2. Configure Klaro services
You manage services in the menu Klaro services. A service offers the following options:
Name (of the service configuration)
In the Name section you can give the service configuration a name. This name helps you find the service configuration easily and distinguish it from other configurations.
Service name, purposes and cookie rules
In the second section you define the service name, the assignment of purposes and the cookie rules.
Please note that these parameters always refer to only one service. Please also note that the name of the service configuration and the service name are two different things! The name of the service configuration is meant to help you organize and distinguish many configurations, whereas the service name is used internally by Klaro.js and is important. If the service name is defined incorrectly, Klaro does not work correctly! As we don’t know exactly how Klaro handles this string internally, we recommend using only lowercase letters and hyphens here. Our Contao Klaro module allows all characters, but we don’t know whether Klaro.js accepts them. Feel free to try it out, though.
So you have to enter a string for the service in the field Service name! This field is mandatory! The example shows ‘google-analytics’. We recommend this notation. It is also suggested by the annotated configuration.
Next you can assign the service to different purposes. If no purposes have been defined yet, this list is empty. You then first have to create new purposes in the menu Klaro purposes. You find more about this below in the section 3. Configure Klaro purposes.
In the image above you also see a purpose [contaoce] translation missing whose name looks a bit odd. You always see this display when a translation for this purpose is missing under Klaro translations. You find more about this below in the section 4. Configure Klaro translations. This also shows nicely that there are many dependencies within the Klaro configuration.
Finally, you can define so-called cookie rules here. We used the examples from the annotated configuration. If you want to understand how these rules work, we recommend a look at the annotated configuration.
Service defaults
Here you configure how the service is preset when the page is first loaded by Klaro.
The options are largely self-explanatory.
With the option accepted you define whether this service is already preset to accepted when the site is opened.
Required means that the user cannot deactivate this service. So use this option for services that are necessary for your website to work at all (e.g. shopping cart cookies etc.).
If the option force is enabled, Klaro loads the service even if the visitor has not yet consented to it. The Klaro developers advise against using it, as it contradicts the concept of self-determined privacy.
If the option once is enabled, the service is only requested once by Klaro, no matter how often the user switches it on and off. This matters, for example, for tracking scripts that create a new request every time Klaro notices a change of consent by the user.
If the option contextual is enabled, Klaro treats the service as »contextual«. This means that a separate consent is requested at the corresponding positions in the layout before the content of the element is shown.
Callback definition
You can skip this point. It is only relevant for experienced users!
As mentioned in the section 1. Klaro configuration, Klaro supports certain callbacks. Here you can define a callback (more precisely the function body) for the service.
3. Configure Klaro purposes
There is not much to say about the Klaro purposes. Klaro uses them to create an internal assignment to the services.
Conversely, each service can be assigned one or more purposes.
Name and Klaro key (purpose key)
For the name of the purpose you can enter any string.
For the Klaro key it is important to use only lowercase letters and hyphens. Klaro uses this string internally as a JavaScript object key, and – put simply – it must not contain any other characters.
4. Configure Klaro translations
Finally, we come to the Klaro translations. Klaro is designed for multilingual use throughout. This (unfortunately) also opens up a great many configuration options. As not all elements need to be configurable by the user and this can quickly become confusing, we have only made selected translations accessible. We based the selection on everyday use.
As Klaro is relatively tolerant (meaning that in case of errors it tries not to block or hinder the website it runs on), we followed this concept for the translations. This means you can enter translations incorrectly or not at all. Of course, texts will then be missing or you will get odd output. But that’s up to you…
The Klaro translations offer the following options:
Name of the translation
As there can be many translations, we follow our habit here and offer a name for the translation.
It is a string you can choose freely; the field is mandatory.
We recommend following the Klaro annotated configuration for the naming. There the languages are defined by
language codes according to ISO 639-1. So we recommend naming them as in the following image:
Language code and link to the privacy policy
Next you set the language code (the country code). Klaro uses ISO 639-1 codes.
Below the language code you can select a link to a page with your privacy policy in the respective language.
Two important notes:
As the Contao Klaro module takes its language from the website root (root page), no further configuration is needed
by the user. If Klaro ever shows the wrong language on your website, first check
whether the language code of your Klaro translation matches the language code currently selected in the
root page. The Contao Klaro module configures the KlaroConfig using the language code of the
root page. Contao’s own language fallback is not taken into account in our module, as Klaro brings its own fallback
concept. Perhaps this will be implemented later…
Internally, Klaro also uses a so-called language fallback code: zz. According to the annotated configuration you should therefore also define a translation for the language zz. We did not get clearly reproducible results with it. According to the annotated configuration, elements from zz should be shown when other languages are not defined. However, we observed that Klaro prefers the translations of the fallback language zz over the correctly defined translations of other language codes, so that the actual (current/desired) language is not shown. It may therefore be necessary not to define zz at all, or to define it in the desired language. Just try it out…
Text in the consent box (Klaro notice)
Here you can enter a text or any (well, not quite – but try it!) HTML. The
TinyMCE editor helps you with this. Here you also find the example text from this explanation:
“Consent Notice Text 4096 Zeichen und HTML Text”. If you look closely, you can see
that this consent notice is shown in bold and italics. That is already simple HTML. If instead you see the
tags themselves, i.e. <b>Consent</b> (or similar), you may not yet have enabled the option HTML mode under
Klaro configuration -> Configure the consent notice -> HTML mode.
We limited the number of characters to 4096.
Klaro lets you define two different texts: the one just mentioned for the consent box (the Klaro notice)
and a different text for the modal window. Here you set the text for the modal window.
This output also supports HTML code, as described above. The number of characters is limited to 4096.
Translation table for registered purposes
Now follow two tables for the translations. We start with the translation of the purposes.
All translation tables work in a similar way, so here is some basic information first.
For Contao insiders: As a translation is in the simplest case a key-value mapping, we implemented
this function with the KeyValueWizard. This is a compromise between performance and usability, because the
KeyValueWizard is unfortunately not ideally equipped for this use. Here you can assign a translation to each
previously defined purpose (key). The correct key must be entered under key.
If you enter an unknown key or make a typo, you cannot save the record.
As you can’t keep all keys in your head at the same time, the error message and a little helper
we built in assist you. You can see from the error message which keys
are allowed and where the typo might be.
We built in a little helper that automatically re-enters the already registered keys for you. So if everything went wrong, simply delete all elements from the table. At the end, one key-value pair remains. Delete the contents of these fields as well and save the record with the Save button. In this situation the widget determines all registered keys again and pre-fills the table. You then only have to add the translations (see the image in the previous note).
Translation table for registered services
There is not much to add here. In this table you define the translation for registered services.
Otherwise, everything said for the previous table applies.
Translations for contextual consent
While working with Klaro we noticed that some texts and labels don’t quite fit the problem that
is being solved. We noticed this, for example, when displaying elements for which no consent had been given yet.
So we thought it would be good to be able to adjust these texts as well. The default configuration
looks like this, for example:
Yes or Always? That is somewhat unclear, especially considering that we also want to welcome
visitors who speak other languages on our website. That is why we added an option to customize this placeholder.
In the field Question text you can now phrase the question in more detail. Klaro.js offers the variable {title} here, which is replaced by the name of the assigned service (don’t ask why service.name is called title here). In the image you can see that at this position the consent for the service »YouTube« is requested. The left button gives a one-time consent (until the next request / reload of the page), so we labelled it »once«.
The right button gives consent until revoked (via the Klaro manager alias modal window), hence this
label.
