Configuration object

In this section, we will describe the structure of the banner configuration object to illustrate what is actually inserted into the page through the script.

The configuration object is a JSON containing the parameters required to generate the banner. As mentioned earlier, the object is generated by the Avacy SaaS platform from the designated section for a specific domain group, and each label corresponds to a specific input field in the SaaS. Any changes made to the banner result in overwriting the configuration object with the updated values, implying that there is no versioning of the banner.

{ 
    "auto_language": true,
    "customVendorListUrl": "https://cdn.url.test/custom-vendor-list.json",
    "logo_url": "https://icons-for-free.com/iconfiles/png/512/cookie-1319971784454690183.png",
    "close_without_consents": true,
    "publisher": "publisher_name",
    "deviceEnvironment": "web", // oppure 'native' per ambiente mobile
    "config_version": 1,
    "policy_version": 2,
    "advanced_settings": true,
    "iabVendorListUrl": "https://cdn.test.it/assets/",
    "timeout": -1,
    "poi_activate_poi": false,
    "poi_group_name": "PoiGroupName",
    "poi_hub_origin": "https://test.jumpgroup.it",
    "poi_hub_path": "/hub.html",
    "show_limited_vendors_only": true,
    "iabVendorWhitelist": [3, 4, 5],
    "atpWhitelist": [39, 43, 46],
    "additionalConsentUrl": "https://cdn.test.it/assets/additional-consent-providers.json",
    "publicPath": "/",
    "cookie_expires_in_days": 15,
    "language": "it",
    "languages": {
      "it": {
        "localeId": "it",
        "version": 1,
        "texts": {
          "label_intro_heading": "Cookies and Advertising on This Site",
          "label_button_yes": "I Consent",
          "label_intro": "This site uses cookies and similar tools, including third-party ones, to measure consumption and ensure the enjoyment of digital content, facilitate navigation, and offer targeted advertising. To learn more, you can view the extended policy <a href=\"https://www.test.it/privacy/CookiePolicy.html\" target=\"_blank\">by clicking here</a>. To deny consent or manage your preferences, use the \"EXPRESS PREFERENCES\" button. By pressing \"I CONSENT\", you agree to the use of cookies and similar tools.",
          "label_cpc_heading": "Cookies and Advertising on This Site",
          "label_cpc_text": "You can view the Extended Cookie Policy at the following <a href=\"https://www.test.it/privacy/CookiePolicy.html\" target=\"_blank\">link</a>.",
          "label_cpc_activate_all": "Activate All",
          "label_cpc_deactivate_all": "Deactivate All",
          "label_third_party": "IAB TCF Compliant Vendors",
          "label_cpc_purpose_title": "Purposes",
          "label_cpc_special_purpose_title": "Special Purposes",
          "label_cpc_feature_title": "Features",
          "label_cpc_special_feature_title": "Special Features",
          "label_cpc_read_less": "Read Less.",
          "label_cpc_read_more": "Read More...",
          "label_button_back": "Back",
          "label_button_advanced_settings": "Express Preferences",
          "label_custom_thirdparty_heading": "Other Vendors",
          "label_third_party_object_legint": "Legitimate Interest for Vendors",
          "label_cpc_purpose_optout_confirm_heading": "Are You Sure?",
          "label_cpc_purpose_optout_confirm_text": "These settings will change your experience on the site.",
          "label_cpc_purpose_optout_confirm_proceed": "Continue",
          "label_cpc_purpose_optout_confirm_cancel": "Cancel",
          "label_poi_group_list_heading": "Business Units List",
          "label_poi_group_list_text": "Business Units",
          "label_thirdparty_list_heading": "Your Consent for Third-Party Software",
          "label_thirdparty_list_text": "Here is a list of third-party software.",
          "label_nocookie_head": "In order to be able to provide our services in the best possible way, cookies must be activated in your browser.",
          "label_nocookie_text": "Please activate cookies in your browser settings. You can do this in <a href=\"https://support.google.com/chrome/answer/95647?co=GENIE.Platform%3DDesktop&amp;hl=en-GB\" class=\"as-oil__intro-txt--link\" target=\"_blank\">Google Chrome</a> or <a href=\"https://support.mozilla.org/en-US/kb/cookies-information-websites-store-on-your-computer\" class=\"as-oil__intro-txt--link\" target=\"_blank\">Firefox</a>.",
          "label_cpc_legal_purpose_consent": "Purposes (Consent)",
          "label_cpc_legal_purpose_leg_int": "Purposes (Legitimate Interest)",
          "label_cpc_legal_special_purposes": "Special Purposes",
          "label_cpc_legal_features": "Features",
          "label_cpc_legal_special_features": "Special Features",
          "label_third_party_description": "These services comply with the <a target=\"_blank\" href=\"https://iabeurope.eu/transparency-consent-framework/\">IAB Transparency and Consent Framework (TCF)</a>.",
          "label_cpc_save": "Save and Continue",
          "label_cpc_legint_box_text": "Allow this service to process your data based on legitimate interest.",
          "label_cpc_legint_infobox_title": "Legitimate Interest",
          "label_cpc_legint_infobox_description": "A \"legitimate interest\" is an interest that, according to applicable legislation, justifies the processing of personal data.<br>Services that choose to rely on a legitimate interest can process your data unless you object to such processing.<br><p><b>By unchecking this box, you exercise your right to object.</b></p>",
          "label_additional_consent_heading": "Google Partner"
        }
      }
    },
    "visual_configuration" : {
      "colors": {
          "text_color_primary": "#80888c",
          "text_color_secondary": "#262628",
          "background_color": "#f9f9f9",
          "secondary_background_color": "#dedede",
          "accent_primary": "#0099f2",
          "btn_primary_background": "#0099f2",
          "btn_primary_background_hover": "#0d9ef3",
          "btn_primary_text_color": "#ffffff",
          "btn_secondary_background": "#0099f2",
          "btn_secondary_background_hover": "#0d9ef3",
          "btn_secondary_text_color": "#ffffff",
          "btn_disabled_background": "#dfdfdf",
          "btn_disabled_text_color": "#545454",
          "slider_background": "#b1b6b8",
          "slider_background_circle": "#ffffff",
          "third_parties_background": "#eff0f0"
      },
      "banner_position": "PositionBottom",
      "banner_animation": "SlideIn", 
      "font_base_scale": 1,
      "font_family": "Montserrat"
    }
}

Currently, this JSON is stored in a remote storage, and the script with the oil-configuration ID integrated into the page retrieves it to display the banner according to the user’s desired configuration.

Although this is the default setup, it is possible to manually override the configuration parameters by modifying the script and inserting a JSON object with the keys you wish to change and their respective values. For example, to change the parameter related to the consent validity period, you simply need to include an object within the script in the following manner:

<script id="oil-configuration" type="application/configuration" data-remote-config="https://avacy-cdn.url/domain-group-uuid.json">
       {
           "cookie_expires_in_days": "180"
       }
</script>

In this way, the value of the parameter cookie_expires_in_days taken from the remote configuration will be overridden by the manually inserted value. Essentially, values set in this manner take precedence over those present in the remote configuration.

Below is a table with additional information for each parameter present in the configuration object. For each parameter, it is possible to perform an override as shown previously.

General settings

Generic Configuration Values

Parameter	Description	Type
config_version	Version of the configuration object	int
policy_version	Version of the current privacy policy	int
timeout	Timeout for auto-optin (-1 to disable)	int \| -1
publicPath		string
cookie_expires_in_days	Expiration time of the OIL cookie	int
language	Initial language of the banner
auto_language	Flag for automatic reading of the HTML page's lang attribute	bool
advanced_settings	Enables the preferences panel	bool
close_without_consents	Enables the ‘x’ to reject all	bool
reject_all	Enables the ‘Reject All’ button	bool
use_legint	Enables legitimate interest	bool
useStacks	Enables display in stacks	[int]

Power-Optin Management

Parameter	Description	Type
poi_activate_poi	Power-optin activator	bool
poi_group_name	JSON file name containing the group members	string
poi_hub_origin	URL of the power-optin hub	string
poi_hub_path	Relative path to the hub origin	string

IAB Management

Parameter	Description	Type
iabVendorListUrl	Base URL from which the GVL retrieves the vendor list	string
iabVendorWhitelist	Array containing the IDs of visible vendors	[int]
show_limited_vendors_only	Flag to show only the IAB vendors in the whitelist	bool

Additional Consent Management

Parameter	Description	Type
additionalConsentUrl	URL pointing to the JSON containing additional consent vendors	string
atpWhitelist	Array of visible vendors	[int]

Custom Vendors Management

Parameter	Description	Type
CustomVendorListUrl	URL pointing to the JSON containing custom vendors	string

SDK management

Parameter	Description	Type
publisher	Name of the publisher if you want to customize SDK management	string
deviceEnvironment	Environment in which the banner is used (“web”, “native”)	string

Languages Object

Parameter	Description	Type
languages	Object containing all strings divided by lang_code	object

Generals

Parameter	Description	Type
logo_url	URL of the logo to display	string
font_base_scale	Multiplier for the base font size	number
font_family	Name of the font family to apply	string

Colors

Parameter	Description	Type
colors	Object containing all the colors for the banner	object

Behaviour

Parameter	Description	Type
banner_position	Position of the banner, configurable in 5 different ways.	string
optin_on_scroll	Indicates whether consent can be given via scrolling.	bool
optin_scroll_amount	Indicates the amount of scroll required for consent to be given.	int
animation	Animation on entry chosen between Opacity and Slide.	string
require_optout_confirm	Boolean value that enables or disables the confirmation modal for opting out of consents. If not specified, the default value is false.	bool

Banner Texts

First layer

Parametro	Descrizione
Bottoni
label_button_yes	Label pulsante per accettazione
label_button_advanced_settings	Label pulsante pannello preferenze
label_button_reject_all	Label pulsante per rifiuto
Testi
label_intro_heading	Titolo pannello layer 1
label_intro	Testo introduttivo

Second layer

Button and Text Labels

Parameter	Description
Buttons
label_cpc_activate_all	Label for the ‘Activate All’ button.
label_cpc_deactivate_all	Label for the ‘Reject All’ button.
label_button_back	Label for the ‘Back’ button.
label_cpc_read_less	Label for the ‘Read Less’ button.
label_cpc_read_more	Label for the ‘Read More’ button.
label_cpc_save	Label for the ‘Save and Continue’ button.
Texts
label_cpc_heading	Title for the layer 2 panel.
label_cpc_text	Introductory text for the internal panel.
Purpose Texts
label_cpc_purpose_title	Title for the purpose section.
Special Purpose Texts
label_cpc_special_purpose_title	Title for the special purpose section.
Feature Texts
label_cpc_feature_title	Title for the feature section.
Special Feature Texts
label_cpc_special_feature_title	Title for the special feature section.
IAB and Custom Vendor Details
label_cpc_legal_purpose_consent	Label for the vendor purpose details.
label_cpc_legal_special_purposes	Label for the vendor special purpose details.
label_cpc_legal_features	Label for the vendor feature details.
label_cpc_legal_special_features	Label for the vendor special feature details.
label_cpc_legal_purpose_leg_int	Label for the vendor purpose details (legitimate interest).
IAB
label_third_party	Title for the IAB sidebar tab.
label_third_party_description	Description text for the IAB section.
Other Providers (Custom Vendors)
label_custom_thirdparty_heading	Title for the sidebar tab for other providers.
Additional Consent
label_additional_consent_heading	Title for the sidebar tab for additional consent.
Legitimate Interest
label_third_party_object_legint	Text for the toggle to activate legitimate interest for third parties.
label_cpc_legint_box_test	Text for the legitimate interest checkbox.
label_cpc_legint_infobox_title	Title for the legitimate interest infobox.
label_cpc_legint_infobox_description	Description text for the legitimate interest infobox.
TCF 2.1
label_cpc_cookie_disclosure_info	Label for the 'More Information' button.
label_cpc_disclosure_panel_title	Title for the Additional Information panel.
label_cpc_disclosure_duration_prefix	Prefix for the disclosed cookie duration.
label_cpc_retention_snippet_session	Label for session duration.
label_cpc_retention_snippet_undefined	Text for undefined duration.
label_cpc_disclose_cookie_identifier	Text for the disclosed cookie ID.
label_cpc_disclose_cookie_type	Text for the disclosed cookie type.
label_cpc_disclose_cookie_domain	Text for the disclosed cookie domain.
label_cpc_disclose_cookie_duration	Text for the disclosed cookie duration.
label_cpc_disclose_cookie_purposes	Text for the disclosed cookie purposes.
Stack Usage
label_cpc_more_stack	Text for opening stack details.
label_cpc_less_stack	Text for closing stack details.

To re-display the banner and modify the consent, you can call the showPreferenceCenter() in two modes:

absolute: Displays the Preference Center in the same style and position as the initial Cookie Banner. In this case, it is not necessary to specify the <div> tag with the id oil-preference-center.
inline: shows the Control Panel exactly where the tag is inserted
```
<div id="oil-preference-center"></div>.
```

If no parameters are entered, the method will behave by default as if it were "inline", and will show the Control Panel as the last visible element of the body.

Addition of custom vendors

Custom Vendors are vendors that do not support the IAB standard. Avacy supports the ability to insert a list of custom vendors. This is possible from the SaaS by inserting a URL to a JSON file that contains the list with the aforementioned vendors.

In the image we see the result of adding a Custom Vendors within the banner configuration. The section is located under IAB vendors in the preferences panel.

alt_text

First you need to create a json file containing the list of desired Custom Vendors.

For each custom vendor it is necessary to specify:

a unique id;
a name that will be shown in the banner;
the URL of the custom vendor policy;
the ids of the associated purposes;
two Javascript snippets one for opt-in and one for opt-out. These snippets are launched when the user updates the consent.

We report an example of a list of custom vendors where the Google vendor has been added with related purposes and snippets.

{
  "vendorListVersion": 123,
  "lastUpdated": "2018-11-27T01:25:33+01:00",
  "vendors": [
    {
      "id": "Google",
      "name": "Google",
      "policyUrl": "https://support.google.com/admanager/answer/9012903?hl=it",
      "purposeIds": [1, 2, 4],
      "optInSnippet": "hasGoogleConsent=true", 
      "optOutSnippet": "hasGoogleConsent=false"
    }
  ]
}

Next, you need to make two changes to the global object for the banner to reflect the addition of the custom vendor list.

To this object, add the customVendorListUrl parameter, i.e. the public URL containing the previously created JSON (e.g. "//avacy.it/custom-vendors.json" ); finally, the following labels must be added to the banner configuration object, within each language that composes it:

label_custom_thirdparty_heading: the label text for the cookie preference center of the custom vendors section.

         "texts":{
            // ...            
            "label_cpc_heading":"Cookie preferences center",
            "label_third_party":"Suppliers participating in IAB TCF",
            "label_custom_thirdparty_heading " : "Other vendors",
            "label_intro_heading":"We use cookies and other technologies",
            // ...

Visual configuration

The visual configuration part of the banner is represented by the portion of the configuration object identified by the visual_configuration key

The following object contains default values.

 "visual_configuration" : {
            "colors": {
                    "text_color_primary": "#80888c",
                    "text_color_secondary": "#262628",
                    "background_color": "#f9f9f9",
                    "secondary_background_color": "#dedede",
                    "accent_primary": "#0099f2",
                    "btn_primary_background": "#0099f2",
                    "btn_primary_background_hover": "#0d9ef3",
                    "btn_primary_text_color": "#ffffff",
                    "btn_secondary_background": "#0099f2",
                    "btn_secondary_background_hover": "#0d9ef3",
                    "btn_secondary_text_color": "#ffffff",
                    "btn_disabled_background": "#dfdfdf",
                    "btn_disabled_text_color": "#545454",
                    "slider_background": "#b1b6b8",
                    "slider_background_circle": "#ffffff",
                    "third_parties_background": "#eff0f0"
            },
            "banner_position": "PositionBottom",
            "banner_animation": "SlideIn", 
            "font_base_scale": 1,
            "font_family": "Montserrat"
 }

Colors:
Label	Meaning
text_color_primary	Primary text color
text_color_secondary	Secondary text color
background_color	Banner background color
secondary_background_color	Secondary banner background color
accent_primary	Primary accent color
btn_primary_background	Primary button background color
btn_primary_background_hover	Primary button background color on hover
btn_primary_text_color	Primary button text color
btn_secondary_background	Secondary button background color
btn_secondary_background_hover	Secondary button background color on hover
btn_secondary_text_color	Secondary button text color
btn_disabled_background	Disabled button background color
btn_disabled_text_color	Disabled button text color
slider_background	Toggle switch background color
slider_background_circle	Toggle switch circle color
third_parties_background	Background color of the third parties section

Label	Description	Possible Values
banner_position	Banner position	Top, Bottom, Top Center, Bottom Center, Center
banner_animation	Entrance animation	Opacity, Slide
font_base_scale	Text size	Small, Medium, Large, Custom size
font_family	Specifies the font family for the text. Must include the font.

Configuration object

General settings

Banner Appearance

Banner Settings

Banner Texts

Button and Text Labels

Addition of custom vendors

Visual configuration

Configuration object

General settings

Banner Appearance

Banner Settings

Banner Texts

Button and Text Labels

Consent handling

Addition of custom vendors

Visual configuration