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
- types (Array<string>) –
-
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 are new in the setup and for which the decision has not yet been saved in the ppms_privacy_[appId] cookie.
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
- types (Array<string>) –
-
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 consent1
- 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 decision0
- user has rejected consent1
- 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 requestview_data
for view data requestdelete_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
Open consent form¶
New in version 12.0.
Opens the consent form. Works only for built-in consent forms, it will not do anything if the “custom consent form” mode is enabled.
Code:
ppms.cm.api('openConsentForm', onFulfilled, onRejected);
-
onFulfilled
(popupId, consentTypes, consents) The fulfillment handler callback
Arguments: - popupId (string) –
ID of the consent form
Example:
'ppms_cm_consent_popup_30a851b6-6bf4-45f9-9a53-583401bb5d60'
- consentTypes (array<string>) –
Array of consent types
Example:
['analytics', 'conversion_tracking', 'remarketing']
- consents (array<string>) –
Array list of all given consents
Example:
['analytics', 'remarketing']
- popupId (string) –
-
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 consent form view¶
New in version 15.3.
Tracks a consent form view caused by visiting 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’s consent form view¶
New in version 15.3.
Tracks a consent form view caused by clicking on the 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 privacy policy link’s consent form view¶
New in version 15.3.
Tracks a consent form view caused by clicking on the privacy policy link.
Code:
ppms.cm.api('trackPrivacyPolicyLinkView', 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.
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
Clear consent settings¶
New in version 18.11.
Clears visitor’s privacy settings. Removes ppms_privacy_[appId] cookie and updates the value of the Consents variable.
Code:
ppms.cm.api('clearConsentSettings', 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
Consent types reference¶
Available consent types:
[ 'analytics', 'ab_testing_and_personalization', 'custom_consent', 'user_feedback', 'marketing_automation', 'remarketing', 'conversion_tracking' ]