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

  • New in version 18.11: Clear consent settings

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

ppms.cm.api(command, ...args)
Arguments:
  • command (string) – Command name
  • args – Command arguments. The number of arguments and their function depend on the 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 an asynchronous snippet installed, then you are able to use the Consent Manager’s JavaScript API.

Commands

All commands work in the context of the current visitor and site or app. Additionally, they sometimes require communication with a Piwik PRO 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 specified, any error object will be passed as an argument. If not specified, an error is reported directly to 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. Outputs types that are used in at least one tag and types that are present in the ppms_privacy_[appId] cookie.

Code:

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

required The fulfillment handler callback (called with the result)

Arguments:
  • types (Array<string>) –

    Required Array of consent types

    Example:

    ['remarketing', 'analytics']

    Available consent types: 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 that a visitor hasn’t seen yet.

Code:

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

required The fulfillment handler callback (called with the result)

Arguments:
  • types (Array<string>) –

    Required Array of consent types

    Example:

    ['remarketing', 'analytics']

    Available consent types: 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 ppms_privacy_[appId] cookie. Use this command to save “no decision” for the available consent types, to further know that a visitor has seen the form. A result from the 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: 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

Sets 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: Consent types reference

Where consent.analytics is the consent type and status indicates:

  • 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: Consent types reference

Where consent.analytics is the consent type and status indicates:

  • -1 - user hasn’t interacted, e.g. has closed a consent popup without any decision
  • 0 - user has rejected consent
  • 1 - user has approved consent
onFulfilled(settings)

required The fulfillment handler callback (called with the 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

Sends a data subject request to the Consent Manager.

Code:

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

required The data subject request

Example:

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

Where type is the 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 Agree to all click

New in version 15.3.

Tracks a click 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.

Tracks a click 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.

Tracks a click 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.

Tracks a click on the consent form’s 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