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

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" src="https://cdn.iubenda.com/consent_solution/iubenda_cons.js"></script>
<script type="text/javascript">
  _iub.cons.init({
    api_key: "YOUR_PUBLIC_API_KEY", // IMPORTANT: CUSTOMIZE WITH YOUR OWN PUBLIC API KEY
  });
</script>
api_key required String Your public key
logger optional String none, console (default)
log_level optional String none, debug, info, warn, error, fatal
sendFromLocalStorageAtLoad optional bool 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 alernative 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
// 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"
}

Callbacks

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

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.

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()
<script type="text/javascript">
_iub.cons.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>"
          }
        ]
    }
  })
</script>

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.

Example 1:

This example is in regards to the MAP feature

Load function

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

Load function with Map (no data-attribute)

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

Example 2:

This example illustrates Submit implementation

Submit implementation

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

Example 3:

This example illustrates Multiple Form implementation

Multiple Form implementation

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

Example 4:

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

Load function with validate.js

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

Still have questions?

Visit our support forum Email us