Documentation

Consent Solution – JS 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
// Coming soon:
sendFromLocalStorageAtLoad optional bool default: true. Determines whether the script reads localStorage at load and submits whatever is included

Consent

Shared between the record 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 TBD. Actually an array of strings
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 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 Selector of the form
// Coming soon:
writeOnLocalStorage Boolean Defines whether the data should be sent directly or written in localStorage. The default changes between the .record (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-.

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 write into the API synchronously.

<script type="text/javascript">
  _iub.cons.submit({
    writeOnLocalStorage: false, *// default: false*
    form: {
      selector: $("#form"), *// The selector of the form where to detect the data*
    },
    consent {
        subject: {
          id: "08487b19456ec8f7678f",
          email: "test10@iubenda.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>

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: $("#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: $("#form"), *// The selector of the form where to detect the data*
    },
    consent: {
        subject: {
          id: "08487b19456ec8f7678f",
          email: "test10@iubenda.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>

Still have questions?

Visit our support forum Email us