JavaScript API

Introduction

Consent Manager provides a JavaScript API that allows the user to:

  • Get compliance types

  • Get new compliance types

  • Set initial compliance settings

  • Set compliance settings

  • Get compliance settings

  • Send data subject request

  • New in version 12.0: Open consent form

  • New in version 15.3: Track consent stats

JavaScript API is implemented by providing global JavaScript objects queue responsible for executing command:

ppms.cm.api(command, ...args)
Arguments:
  • command (string) – Command name
  • args – Command arguments. The number of arguments and their function depend on command.
Returns:

Commands are expected to be run asynchronously and return no value
Return type:

undefined

Consent Manager is fully integrated with Tag Manager. If you already have asynchronous snippet installed, then you are able use Consent Manager’s JavaScript API.

Commands

All commands work in the context of the current visitor and website. Additionally, they sometimes require communication with a PPAS server and are asynchronous. Callback functions are used to provide response value or information about errors. onSuccess(...args) callback is required, with the exception of openConsentForm command where it is optional. onFailure(exception) callback is optional and if is specified, any error object occurred will be passed as an argument. If not specified, an error is reported directly on the console output.

Note

For examples of how to use a specific command in your custom consent form implementation (including how to track consent stats), refer to the Piwik PRO - Custom consent form example

Get compliance types

Fetches a list of consent types for the current setup. For the consent type to appear in the output, at least one tag must have it set.

Code:

ppms.cm.api('getComplianceTypes', onFulfilled, onRejected);
onFulfilled(types)

required The fulfillment handler callback (called with result)

Arguments:
  • types (Array<string>) –

    Required Array of consent types

    Example:

    ['remarketing', 'analytics']

    Available consent types you’ll find here: Consent types reference
onRejected(error)

The rejection handler callback (called with error code). If not specified, the exception will be thrown in the main stack trace.

Arguments:
  • error (string|object) – Required Error code or exception

Get new compliance types

Fetches a list of the consent types which a visitor did not see yet.

Code:

ppms.cm.api('getNewComplianceTypes', onFulfilled, onRejected);
onFulfilled(types)

required The fulfillment handler callback (called with result)

Arguments:
  • types (Array<string>) –

    Required Array of consent types

    Example:

    ['remarketing', 'analytics']

    Available consent types you’ll find here: Consent types reference
onRejected(error)

The rejection handler callback (called with error code).

Arguments:
  • error (string|object) – Required Error code or exception

Set initial compliance settings

Sets initial compliance settings (no decision signal for each consent type) in the cookie. Use this command to save ‘no decision’ for the available consent types, to further know that a visitor has seen the form. Result from getNewComplianceTypes method can be passed directly.

Code:

ppms.cm.api('setInitialComplianceSettings', settings, onFulfilled, onRejected);
settings

required The consent settings object

Example:

{consents: ['analytics']}

or

Example:

['analytics']

Available consent types you’ll find here: Consent types reference

onFulfilled()

required The fulfillment handler callback

onRejected(error)

The rejection handler callback (called with error code). If not specified, the exception will be thrown in the main stack trace.

Arguments:
  • error (string|object) – Required Error code or exception

Set compliance settings

Set compliance settings based on visitor’s decisions. Use this command to save visitor’s consent choices from the consent form. Consent Manager forces a page view after the command is invoked, so all tags requiring certain choices will be fired immediately after the consent is given.

Code:

ppms.cm.api('setComplianceSettings', settings, onFulfilled, onRejected);
settings

required The consent settings object

Example:

{consents: {analytics: {status: 1}}}

Available consent types you’ll find here: Consent types reference

Where consent.analytics is consent type and status indicate:

  • 0 - user has rejected the consent
  • 1 - user has approved the consent
onFulfilled()

required The fulfillment handler callback

onRejected(error)

The rejection handler callback (called with error code). If not specified, the exception will be thrown in the main stack trace.

Arguments:
  • error (string|object) – Required Error code or exception

Get compliance settings

Returns current privacy settings. Use this command to get visitor’s decisions. This command returns an empty object if there were no decisions registered yet.

Code:

ppms.cm.api('getComplianceSettings', onFulfilled, onRejected);
settings

required The consent settings object

Example:

{consents: {analytics: {status: -1, updatedAt: '2018-07-03T12:18:19.957Z'}}}

Available consent types you’ll find here: Consent types reference

Where consent.analytics is consent type and status indicate:

  • -1 - user has not interacted, e.g. has closed a consent popup without any decision
  • 0 - user reject consent
  • 1 - user approve consent
onFulfilled(settings)

required The fulfillment handler callback (called with result)

onRejected(error)

The rejection handler callback (called with error code). If not specified, the exception will be thrown in the main stack trace.

Arguments:
  • error (string|object) – Required Error code or exception

Send data subject request

Command that sends a Data subject request to the Consent Manager.

Code:

ppms.cm.api('sendDataRequest', request, onFulfilled, onRejected);
request

required The subject data request.

Example:

{content: 'user input', email: 'example@example.org', type: 'delete_data'}

Where type is request type, and can be one of:

  • change_data for data alteration request
  • view_data for view data request
  • delete_data for delete data request
onFulfilled()

required The fulfillment handler callback

onRejected(error)

The rejection handler callback (called with error code). If not specified, the exception will be thrown in the main stack trace.

Arguments:
  • error (string|object) – Required Error code or exception

Track Main Form view

New in version 15.3.

Command used to track Consent Form main view (automatic view, when user enters the website for the first time).

Code:

ppms.cm.api('trackMainFormView', onFulfilled, onRejected);
onFulfilled()

The fulfillment handler callback

onRejected(error)

The rejection handler callback (called with error code). If not specified, the exception will be thrown in the main stack trace.

Arguments:
  • error (string|object) – Required Error code or exception

Track Reminder Widget view

New in version 15.3.

Command used to track Consent Form view caused by clicking on Reminder Widget.

Code:

ppms.cm.api('trackReminderWidgetView', onFulfilled, onRejected);
onFulfilled()

The fulfillment handler callback

onRejected(error)

The rejection handler callback (called with error code). If not specified, the exception will be thrown in the main stack trace.

Arguments:
  • error (string|object) – Required Error code or exception

Track Agree to all click

New in version 15.3.

Command used to track clicks on the Agree to all button.

Code:

ppms.cm.api('trackAgreeToAllClick', onFulfilled, onRejected);
onFulfilled()

The fulfillment handler callback

onRejected(error)

The rejection handler callback (called with error code). If not specified, the exception will be thrown in the main stack trace.

Arguments:
  • error (string|object) – Required Error code or exception

Track Reject all click

New in version 15.3.

Command used to track clicks on the Reject all button.

Code:

ppms.cm.api('trackRejectAllClick', onFulfilled, onRejected);
onFulfilled()

The fulfillment handler callback

onRejected(error)

The rejection handler callback (called with error code). If not specified, the exception will be thrown in the main stack trace.

Arguments:
  • error (string|object) – Required Error code or exception

Track Save choices click

New in version 15.3.

Command used to track clicks on the Save choices button.

Code:

ppms.cm.api('trackSaveChoicesClick', onFulfilled, onRejected);
onFulfilled()

The fulfillment handler callback

onRejected(error)

The rejection handler callback (called with error code). If not specified, the exception will be thrown in the main stack trace.

Arguments:
  • error (string|object) – Required Error code or exception

Track close button click

New in version 15.3.

Command used to track clicks on the close button (X).

Code:

ppms.cm.api('trackCloseButtonClick', onFulfilled, onRejected);
onFulfilled()

The fulfillment handler callback

onRejected(error)

The rejection handler callback (called with error code). If not specified, the exception will be thrown in the main stack trace.

Arguments:
  • error (string|object) – Required Error code or exception