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
- 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 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
- 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 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 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 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 decision0
- user reject consent1
- 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 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.
Command used to open consent form. Works only for built-in consent forms, it will not do anything if 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 popup
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 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 Privacy Policy Link view¶
New in version 15.3.
Command used to track Consent Form view caused by clicking on 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.
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
Consent types reference¶
Available consent types:
[ 'analytics', 'ab_testing_and_personalization', 'custom_consent', 'user_feedback', 'marketing_automation', 'remarketing', 'conversion_tracking' ]