Documentation

Consent Solution – JS Documentation

The Consent Solution JavaScript library allows you to record and retrieve consent actions performed by your users, which will be referred to from now on as subjects.

The Consent Solution JavaScript library has the following features:

  • Directly write into the Consent Solution API
  • Write both synchronously or asynchronously, optionally leveraging localStorage
  • Set it to watch a specific form and track consent at submit, or programmatically
  • Supports most browsers (IE8+)
  • Provides callbacks
  • Comes with logging features

Caution

If you have installed ConS prior 03/04/2019 and you want to move to the new ConS Version please refer to this section (at the end of this post).

Setup

To install the Consent Solution JS widget, paste the following code inside every page of your site, before the closing of the HEAD tag.

<script type="text/javascript">
    var _iub = _iub || {};
    _iub.cons_instructions = _iub.cons_instructions || [];
    _iub.cons_instructions.push(["init", {api_key: "YOUR_PUBLIC_API_KEY"}, YOUR_CALLBACK_FUNCTION]);
</script>
<script type="text/javascript" src="https://cdn.iubenda.com/cons/iubenda_cons.js" async></script>

Consent instructions

_iub.cons_instruction is an array where instructions can be pushed before the consent solution has been loaded. After loading, all instruction contained in the array it will be executed.
The instructions will have to comply with the following syntax: [<function name>, [Parameter1][, Parameter2] … ] (see the examples below)

Init callback function

The second parameter of the init function is the callback function. The callback function will be called only after the library has been loaded (see example here).

api_key required String Your public key
logger optional String none, console (default)
log_level optional String none, debug, info, warn, error, fatal
Coming soon:
sendFromLocalStorageAtLoad optional Boolean default: true. Determines whether the script reads localStorage at load and submits whatever is included

Consent

Shared between the submit and load methods

Fields

Shared with the HTTP API:

timestamp auto-filled if not provided String ISO 8601 timestamp at which the consent occurred
subject Object
id auto-filled if not provided String
email optional String
first_name optional String
last_name optional String
full_name optional String
verified optional Boolean Reserved field used to signal whether a subject is verified, for instance via the double opt-in method
legal_notices optional Array Array of objects containing legal_notices data
identifier optional Text
version auto-filled if not provided Text
proofs optional Array Array of objects containing proof data
content optional Text
form optional Text
preferences optional Object Set of key-value pairs with user preferences for the consent action

Note: In the JS library, all of the properties must be specified from within the consent object. Example:

consent: {
    subject: {
      id: "08487b19456ec8f7678f",
      email: "test10@iubenda.com"
    },
    preferences: {
      terms: true
    }
}

Unique to the JavaScript library:

form Object
selector DOM Object Selector of the form
map Object Object allowing to map Consent attributes to specific form fields by their “name” attributes as an alternative to data-cons-x attributes
subject Object
id String name attribute of a DOM element present in the form
email String name attribute of a DOM element present in the form
first_name String name attribute of a DOM element present in the form
last_name String name attribute of a DOM element present in the form
full_name String name attribute of a DOM element present in the form
preferences Object
preference_name String name attribute of a DOM element present in the form
exclude Array a list of fields name that you’d like to exclude from proofs
Coming soon:
writeOnLocalStorage Boolean Defines whether the data should be sent directly or written in localStorage. The default changes between the .submit (false) and .load (true) methods.

More on the Form object

Using the form object, you can configure the JavaScript library to automatically extract the necessary data from a form. In order to tell to the library how to match specific fields, you can use data- attributes, with the prefix data-cons- or map each field by its name attribute using the map object.

For example, this is how you could tag your email input:

<input type="text" name="email" data-cons-subject="email" />

You can also exclude certain fields:

<input type="password" name="password" data-cons-exclude />

Other examples of data- attribute are:

  • data-cons-subject="first_name"
  • data-cons-subject="last_name"
  • data-cons-subject="full_name"
  • data-cons-subject="email"
  • data-cons-preference="privacy_policy"
  • data-cons-exclude

In case there is a conflict between data coming from the form object and data specified directly in the consent object, the consent object will take precedence.
If form is specified, the library will also take care of automatically filling the proof object for you.

Response

200 OK
{
  id: "de801ca9-abec-45e2-8f7c-729822cfffad",
  timestamp: "2018-05-04T14:52:26Z",
  subject_id: "J02eZvKYlo2ClwuJ1"
}

Submit

The submit method allows you to send the Consent data to iubenda APIs synchronously.

<script type="text/javascript">
  _iub.cons.submit({
    form: {
      selector: document.getElementById("form"), // The selector of the form where to detect the data
      map: { // optional: map consent attributes directly to the corresponding
             // input's "name" attribute, instead of using data-cons-x attributes
        subject: {
            email: "email-element-name",
            first_name: "first-name-element-name",
            last_name: "last-name-element-name"
        },
        preferences: {
            terms: "terms-checkbox-element-name"
        }
      }
    },
    consent: {
        subject: {
          id: "08487b19456ec8f7678f",
          email: "user@example.com"  // This will overwrite the subject email that is passed via the form
        },
        preferences: {
          terms: true
        },
        legal_notices: [
            {
              identifier: "privacy_policy",
              version: "12"
            }
        ],
        proofs: [
          {
            content: "{ "first_name": "John", "last_name": "Doe", "email": "john@example.com" }"
            form: "<form action="/action" method="POST"><p><label>First Name</label><input type="text" name="first_name" /></p><p><label>Last name</label><input type="text" name="last_name" /></p><p><label>E-mail</label><input type="email" name="email" /></p><input type="submit" /></form>"
          }
        ]
    }
  })
  .success(function (response) {
    // Success callback
  })
  .error(function (response) {
    // Error callback
  });
</script>

Note: If you use iubenda for your legal documents, we’ll automatically update the contents of the legal_notices method for you whenever your legal documents are changed. You can read about how to enable this feature here.

Callbacks

The .success callback is available in case of success, the .error callback is available in case of error.

Load

The load method allows you to load values into the method that can be then written at a later time, either by setting up a trigger function under submitElement: or programmatically via a dedicated trigger. By default, this method writes into localStorage, to protect from any loss of data in case a new page is loaded before the JavaScript has finished executing.

Specific to the load method:

submitElement optional Select an element that will trigger the submit of the consent, when clicked. If this element is not specified, or not triggered, you can always use _iub.cons.sendData() to submit the consent with the parameters contained in _iub.cons.load()
_iub.cons_instructions.push(["load",{
    submitElement: document.getElementById("submit_button"), // if this line is missing, the consent is sent only when _iub.cons.sendData is triggered
    // WHAT FOLLOWS IS IDENTICAL TO THE .submit call
    form: {
      selector: document.getElementById("form"), // The selector of the form where to detect the data
    },
    consent: {
        subject: {
          id: "08487b19456ec8f7678f",
          email: "user@example.com"  // This will overwrite the subject email that is passed via the form
        },
        preferences: {
          terms: true
        },
        legal_notices: [
          identifier: "privacy_policy",
          version: "12"
        ],
        proofs: [
          {
            content: "{ "first_name": "John", "last_name": "Doe", "email": "john@example.com" }"
            form: "<form action="/action" method="POST"><p><label>First Name</label><input type="text" name="first_name" /></p><p><label>Last name</label><input type="text" name="last_name" /></p><p><label>E-mail</label><input type="email" name="email" /></p><input type="submit" /></form>"
          }
        ]
    }
  }])

sendFromLocalStorage

The sendFromLocalStorage method allows you to send the Consent data previously stored in local storage. Normally, the init script will send any consent stored on local storage at every page load if sendFromLocalStorageAtLoad is set to true.

_iub.cons.sendFromLocalStorage()

Implementation examples

Included below are some practical examples of how you can actually implement the Consent solution.

1. MAP feature

Load function

See the Pen [Iubenda Cons] (async) Load function by iubenda (@iubenda) on CodePen.

Load function with Map (no data-attribute)

See the Pen [Iubenda Cons] (async) Load function and Map option by iubenda (@iubenda) on CodePen.

2. Submit implementation

This example illustrates Submit implementation

See the Pen [Iubenda Cons] (async) Submit implementation by iubenda (@iubenda) on CodePen.

3. Multiple Form implementation

This example illustrates Multiple Form implementation

See the Pen [Iubenda Cons] (async)Multiple Form implementation by iubenda (@iubenda) on CodePen.

4. External validation tools (Load function with validate.js)

This example illustrates how to use external validation tools: Load function with validate.js

See the Pen [Iubenda Cons] (async) load function with validate.js by iubenda (@iubenda) on CodePen.

How to update ConS installations prior to 03/04/2019

If you have installed the iubenda Consent solution before 03/04/2019, in order to use the currently updated version you need to update the way in which you were using the load and the init methods.

LOAD

BEFORE:

_iub.cons.load({ ... your options })

AFTER:

_iub.cons_instructions.push(["load", { ... your options })

INIT

BEFORE:

_iub.cons.init({api_key: "YOUR_PUBLIC_API_KEY"}, YOUR_CALLBACK_FUNCTION]);

AFTER:

_iub.cons_instructions.push(["init", {api_key: "YOUR_PUBLIC_API_KEY"}, YOUR_CALLBACK_FUNCTION]);

Still have questions?

Visit our support forum Email us