Developers

Consentua is a consent management system. It collects consent from your users and allows you to check, in real-time, whether you currently have consent to a specific purpose. Organisations use Consentua to keep detailed records about what they do (and don’t) have consent to do with people’s personal data.

There are two main ways that developers can use Consentua.

Collecting Consent, by embedding consent interactions into Websites or apps using our WebSDK.

Checking for Consent, by querying consent records via our API.

Some organisations also develop for a third use case:

Building new ways of asking for Consent, using the interaction side of our WebSDK.

Whichever case you’re currently implementing, we have tutorials and example code available.

How Consentua Works

There are a few key concepts that you need to be familiar with in order to understand how Consentua works. This quick scenario explains the most important parts of the Consentua world.

Bob Corp would like to get consent from Alice to send her a monthly email newsletter. Sending the newsletter is a Purpose.

To collect Consent, Bob Corp needs to create a Consent Template. Consent Templates include one or more Purposes, and specify a Consent Interaction that should be used to ask for consent. A Consent Interaction is a specific user interface that can display the Consent Template to a user. Consentua provides some Consent Interactions to cover common scenarios, but you can also create new ones using HTML, CSS and Javascript.

Bob Corp embeds the Consent Template into their web page using the Consentua WebSDK. The WebSDK loads the defined Template and the Consent Interaction that should be used to display it. When the interaction is displayed to Alice in her Web Browser, a new Consentua User ID is created in Consentua. Bob Corp stores the Consentua User ID – along with other information about Alice – in their customer database.

When Alice interacts with the Consent Interaction to give (or not give!) her Consent, Consentua stores her responses. If Alice interacts with another Consent Interaction in the future, the same Consentua User ID can be re-used, and so there will be a single record that contains all of Alice’s up-to-date consent responses.

Each month, when Bob Corp are sending their Newsletter, their mailing list system uses Alice’s Consentua User ID to make a request to the Consentua API. The Consentua API indicates whether Alice has consented to different purposes – and the mailing list software can email her – or not – based on whether Consent is available.

Collecting Consent using the Web SDK

Consentua’s WebSDK makes it easy to collect consent in websites and mobile apps. The WebSDK interacts with the Consentua API to load and display consent templates that have been configured.

To embed the WebSDK, you need to know a few pieces of information: The Consentua Client ID of your organisation, the Template ID of the consent template you want to display and – it if already exists – the User ID of the person who you’re asking for consent.

The WebSDK collects and stores consent in the Consentua service. The only thing that you need to store yourself is the User ID. The User ID allows you to look up consent later, when you need it.

To help you get started, we’ve put together a simple example of how Consentua could be embedded in a web form, which you' find at websdk.consentua.com

Checking for Consent

Consent is only useful if it’s joined up with your actual data processing activities. There are two ways that you can check for consent using Consentua. The first is to use the WebSDK - which is convenient in Websites where it’s already deployed for consent collection - but a more general method is to directly integrate with the Consentua API.

The Consentua API is a REST’ful service, accessed via the Web. The full API documentation is available at api.consentua.com

We provide a reference client in Javascript, which will run in most Web browsers or under NodeJS. You'll find it on GitHub, at github.com/Consentua/consentua-client-js/

Building new ways of asking for consent

Consent Interactions are the different interfaces that you can use to ask for consent. Consentua provides some generic interactions out of the box, but you can create new ones to better match the look and feel of your website, to provide new flows, or even to integrate with novel situations like negotiable terms!

Interactions are built using HTML, CSS and Javascript, and are integrated into Consentua using our Web SDK. Custom interactions work just like Consentua’s out-of-the-box interactions, and – once your custom interaction is developed - you don’t need to make any changes to how you embed Consentua. Just register your interaction in Consentua and update your consent templates through the dashboard.

To help explain how custom interactions work, we’ll briefly explain how Consentua serves up consent interactions:

1. When you embed a Consentua template into a website (or an app, using a WebView), the WebSDK loads the Consentua service into an iframe.
2. The Consentua service retrieves the requested template, checks for any existing consent and then loads the interaction that’s configured in the template into another iframe. Communication between the page that’s embedding Consentua, the Consentua Service, and the interaction is handled using cross-document messaging – a feature that’s built into modern Web browsers.
3. When consent is granted, or revoked, the interaction sends a message to the Consentua service; and the Consentua service reacts by saving the new consent state and informing the embedding page.

The separation between the embedding page, the Consentua service, and the interaction makes creating new interactions quite straightforward. You don’t need to worry about interacting with the Consentua Web API directly, because all the functionality that you need is exposed for you to use in javascript via the window.consentua object.

We’ve put together an example to help you get started – you’ll find it at github.com/Consentua/custom-ui-example/

The example assumes that it’s being served from http://127.0.0.1:8080/ (but can be easily tweaked to work for another URL). example.html shows how to embed a custom interaction – during development – by passing an additional option into the ConsentuaEmbed function; and the custom interaction itself is defined in ui/index.html