@signatu/sdk-js

signatu SDK for plain Javascript

Usage no npm install needed!

<script type="module">
  import signatuSdkJs from 'https://cdn.skypack.dev/@signatu/sdk-js';
</script>

README

signatu SDK

The signatu SDK provides a toolkit for integrating signatu Policy- and Consent controls into any Web site or app.

Usage

You can either load the SDK dynamically, or bundle it using a packager such as Webpack.

<script src="https://sdk.signatu.com/v0/sdk.js"></script>

Create a SDK instance

The config object contains credentials. You can create access tokens using OAuth2, or find them in your Credentials page on Signatu.

You can also pre-set properties that you will use in all requests to Signatu - e.g., the subject, issuer and target.

var SignatuService = new Signatu({
  config: {
    apiKey: "ENTER_YOUR_API_KEY",
    accessToken: "ENTER_YOUR_ACCESS_TOKEN"
  },
  subject: Signatu.anonSubject(),
  issuer: "https://your.company",
  target: "https://path.to.your.privacy.policy/"
})

The SDK will hook up components to elements in your DOM, specified by id. Each component has a render() method that takes a properties object and renders the component as a child of the specified DOM element:

<div id="signatu-policy" ></div>
<script>
  SignatuService.PolicyButton.render('signatu-content', {
    policyId: "42",
    language: 'en'
  })
</script>

Themes

The components support customization of their styles using a Theme. You can supply your theme as an (optional) third argument to render():

  var myTheme = {
    palette: {
      primary: {
        main: "red"
      }
    }
  }
  SignatuService.PolicyButton.render('signatu-content', {
    policyId: "42",
    language: 'en'
  }, myTheme);

Refer to https://github.com/signatu/common-react for more information about theming.

Components

  • PolicyButton
  • PolicyLink
  • ConsentCheckbox
  • ConsentButtons
  • CookieBanner
  • PolicyConsentDashboard

Each of the components can also be wrapped in a Popup or CondPopup (conditional popup), so for e.g., ConsentCheckbox there are three components available:

  • ConsentCheckbox
  • ConsentCheckboxPopup
  • ConsentCheckboxCondPopup

The CondPopup has an optional property autoClose which, if set, will close the popup on user action.

Note that the CookieBanner component does not have the Popupand CondPopup components since it is already a popup.

PolicyButton

This component renders a button that when clicked will open the specified Privacy Policy in a separate pop-up window.

  • policyId - you can find this ID as part of the policy permalink - e.g., https://.../api/v0/policies/119/html has policyId 119.
  • color - the color of the rendered button. One of blue, gray, white and black.
  • language - the preferred language. Default: en.
<div id="policy-button"></div>
<script>
  var SignatuService = new Signatu(...)
  SignatuService.PolicyButton.render('policy-button', { policyId: 119 })
</script>

PolicyLink

Renders a standard <a> link. Otherwise the component is identical to PolicyButton above, and has the same arguments.

ConsentCheckbox

ConsentCheckbox displays a consent request consisting of a checkbox, a decriptive text, and an optional title and subtitle.

  • text - the text to be displayed with the checkbox.
  • title - (optional) the title of the request box.
  • subtitle - (optional) the subtitle of the request box.
  • scope - (optional) the scope of the consent.
  • onLoaded - (optional) callback that will be called when the an existing consent event has been loaded.
  • onAction - (optional) callback that will be called when the user takes an action - i.e., ticks or unticks the consent box.
<div id="consent-checkbox" class="signatu-consent"></div>
<script type="text/javascript">
    SignatuService.ConsentCheckbox.render('consent-checkbox', {
      scope: "request-checkbox",
      text: "This is a checkbox!",
      title: "A full consent request using a checkbox",
      subtitle: "You can describe more about the context of the request here.",
      onLoaded: function(consent) {
        /* Do something with the consent event */
      },
      onAction: function(consent) {
        /* Do something with the consent event */
      }
    })
</script>

ConsentButtons

ConsentButtons displays a consent request consisting of two buttons - an Accept and a Refuse - and a decriptive text, and an optional title and subtitle.

The arguments are the same as ConsentCheckbox.

PolicyConsentDashboard

The dashboard will build consent requests (checkboxes) for all the consent targets in the specified Privacy Policy.

  • policyId - the ID of the policy.
<div id="policy-dashboard" class="signatu-consent"/>
<script type="text/javascript">
    SignatuService.PolicyConsentDashboard.render('policy-dashboard', {
      policyId: "119"
    })
</script>

Support functions

anonSubject property is a function you can use as an anonymous identifier for this user on this user agent (e.g., browser, phone). The identifier will be persistent across sessions.

  var userId = SignatuService.anonSubject()

You can clear the subject identifier from the client:

  SignatuService.clearAnonSubject()

Consent Script Loader

The SDK contains a script loader that can load scripts (tags) only if the user has consented to the use.

First, you need to enable it from a valid Signatu object (see above for initialization):

SignatuService.enableConsentScriptLoader()

Now scripts can be conditionally loaded. Tags are annotated with the data-consent tag, as well as the data-consent-scope tag that refers to the scope for this particular 3rd party. Note that you need to have set subject, issuer and target in the Signatu object.

<!-- For external scripts that is using src="..." -->
<script data-consent data-consent-scope="tracker" data-src="https://script.url"></script>

<!-- For external scripts that is included in the page -->
<script data-consent data-consent-scope="othertracker" type="text/plain">
  (function(i,s,o,g,r,a,m)
  ....
  )
</script>

Note the use of type="text/plain" in the second case. This is important to avoid the browser from initially loading the script.

Consent Events

Consent events are posted to the window the control(s) are embedded in.

The format of the events are as follows:

To listen to these events add a listener on the window. The event will be of type object in the data property:

  function isConsentMessage(msg) {
    return msg && msg.data && typeof msg.data === 'object' && msg.data.type === 'signatu-consent-message'
  }

  window.addEventListener('message', (msg) => {
      if (isConsentMessage(msg)) {
          this.handleConsentEvent(msg.data.consent) // <= consent payload
      }
  })

The signatu SDK emits the following events:

event.type Description
signatu-consent-message The consent event as returned from signatu. The event is available in the consent property.

Example event

{
  "type": "signatu-consent-message",
  "consent": {
    "subject": "https://signatu.com/api/v0/ns/cookie/f8d7cad7-dcb1-884e-1af2-395cddb8b08a",
    "issuer": "https://signatu.com/api/v0/datacontrollers/84",
    "target": "https://signatu.com/api/v0/policies/1",
    "action": false,
    "authenticated": null,
    "source": "https://demo.signatu.com/",
    "token": "RRTSJ8",
    "receipt": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUz...",
    "checksums": {
      "target": {
        "sha256": "c80853526596211f30d973d211d...bfb22"
      }
    },
    "id": 334,
    "createdAt": "2016-11-15T13:37:02.634Z",
    "updatedAt": "2016-11-15T13:37:02.639Z"
  }
}