Standard mode

Bv
Last updated last month

Note: This guide is written for a developer audience. If you are looking for the simpler Metomic Auto mode, click here

Getting started

The Metomic library can be loaded into your application either:

Loading as a standalone script

<link rel="stylesheet" href="https://metomic.io/metomic.css"/>
<script src="https://metomic.io/metomic.js"></script>
// Metomic is now available as a global object
var metomic = new Metomic('YOUR_CLIENT_ID')

Loading an npm dependency

npm install --save metomic-js

If you use require(...):

const Metomic = require('metomic-js');
const metomic = new Metomic('YOUR_CLIENT_ID')

You will need to ensure that the css is also loaded into your page. It is bundled with metomic-js under metomic-js/dist/main.css

Or if you use ES6 modules:

import Metomic from 'metomic-js'
// And, assuming your bundler can import css:
import 'metomic-js/dist/main.css'
const metomic = new Metomic('YOUR_CLIENT_ID')

Finally

To use the above snippets, you must replace YOUR_CLIENT_ID with your own clientId. This can be found the in the Developer section of the dashboard.

Using the Metomic SDK

The Metomic SDK exposes a few methods to help manage the consent-based behaviour of your app. All of the following examples assume you have intialised an instance of the Metomic class into a value named metomic

A note on authenticated vs non-authenticated users

Metomic will work for both your authenticated and non-authenticated users, but with a caveat:

Only authenticated users can see or respond to authenticated policies Anonymous users can only interact with anonymous policies

Policies can be configured individually as authenticated or anonymous. By way of example, a cookie policy is likely to be anonymous, as anybody on your website needs to be able to engage with it - not just your logged in users. However, a policy that covers sending marketing materials to your customers ought to be an authenticated policy, as it deals with logged in users.

Authenticating a user

Your server must be configured appropriately for this use case

To manage, audit and surface consents, Metomic needs an id for the user. In the anonymous case, when no id has been provided, Metomic will create it's own - but it is more likely that you will want to query Metomic for the consents of a particular user.

In order to do this securely, it is important that Metomic can trust that the identity the client claims to have is indeed legitimate. For this purpose there is an API method that builds a token for a particular userId, which you can pass in to metomic.authenticate(...).

It is recommended that you generate this token from your backend whenever a user signs in, and pass it forward to the client.

authenticate(...)

Usage: metomic.authenticate(jwtFromServer)

This binds the Metomic session to a particular user. See Authenticating a user section above.

requestConsentFor(...)

Usage: metomic.requestConsentFor(policyId,[cb]) : Promise

Explicitly triggers a modal dialog requesting the user's consent for the policy with id policyId. Returns a promise which is resolved or rejected when the user responds to the consent request. This method also supports passing a callback instead of using a promise.

showCookieWidget()

Usage: metomic.showCookieWidget()

Explicitly raises the cookie widget. It may be helpful to bind this action to a link to your cookie settings, e.g.

<a onclick="javascript:Metomic.showCookieWidget(); return false" href="#" >
Privacy Settings
</a>

--- withConsentFor(...)

Unavailable until version 0.3.0, releasing Friday 2nd November 2018

Usage metomic.withConsentFor(policyId,[cb]) : Promise

Will trigger a consent dialog for policyId if the user has never opted in or out, calling back as appropriate with either success or failure.

If the user has previously made a choice on policy-id in the past, the dialog will not be shown again - instead, cb will be called back immediately with success or failure, depending on the user's choice.

If you wish to explicitly show a consent dialog, use requestConsentFor(...).

--- when(...)

Unavailable until version 0.3.0, releasing Friday 2nd November 2018

metomic.when(policy-id,[cb]) : Promise

Returns a promise that resolves if or when policy is consented to, and is rejected otherwise. This method also supports passing a callback instead of using a promise.