Skip to main content

Consent and GDPR tracking (original)

This plugin has been partially superseded by the Enhanced Consent plugin. This older plugin has only two trackX methods, but it does allow the addition of GDPR context entities to every event.

This plugin is the recommended way to track marketing consent events on your website. Functions, usage and a complete setup journey is showcased on the Consent Tracking for Marketing accelerator.

Original consent events must be manually tracked. The GDPR context entity will be automatically tracked with all events if configured.

Install plugin

Tracker DistributionIncluded
sp.js
sp.lite.js

Download:

Download from GitHub Releases (Recommended)Github Releases (plugins.umd.zip)
Available on jsDelivrjsDelivr (latest)
Available on unpkgunpkg (latest)

Note: The links to the CDNs above point to the current latest version. You should pin to a specific version when integrating this plugin on your website if you are using a third party CDN in production.

window.snowplow('addPlugin', 
"https://cdn.jsdelivr.net/npm/@snowplow/browser-plugin-consent@latest/dist/index.umd.min.js",
["snowplowConsent", "ConsentPlugin"]
);

Events

Use the trackConsentGranted method to track a user opting into data collection. A consent document context will be attached to the event if at least the id and version arguments are supplied. The method arguments are:

NameDescriptionRequired?Type
idIdentifier for the document granting consentYesString
versionVersion of the document granting consentYesString
nameName of the document granting consentNoString
descriptionDescription of the document granting consentNoString
expiryDate-time string specifying when consent document expiresNoString
contextCustom context for the eventNoArray
tstampWhen the event occurredNoPositive integer

The expiry field specifies that the user consents to the attached documents until the date-time provided, after which the consent is no longer valid.

Tracking a consent granted event:

snowplow('trackConsentGranted', {
id: '1234',
version: '5',
name: 'consent_document',
description: 'a document granting consent',
expiry: '2020-11-21T08:00:00.000Z'
});

Use the trackConsentWithdrawn method to track a user withdrawing consent for data collection. A consent document context will be attached to the event if at least the id and version arguments are supplied. To specify that a user opts out of all data collection, all should be set to true.

The method arguments are:

NameDescriptionRequired?Type
allSpecifies whether all consent should be withdrawnNoBoolean
idIdentifier for the document withdrawing consentNoString
versionVersion of the document withdrawing consentNostring
nameName of the document withdrawing consentNoString
descriptionDescription of the document withdrawing consentNoString
contextCustom context for the eventNoArray
tstampWhen the event occurredNoPositive integer

Tracking a consent withdrawn event:

snowplow('trackConsentWithdrawn', {
all: false,
id: '1234',
version: '5',
name: 'consent_document',
description: 'a document withdrawing consent'
});

Consent documents are stored in the context of a consent event. Each consent method adds a consent document entity to the event. The consent document is a custom context entity storing the arguments supplied to the method (in both granted and withdrawn events, this will be: id, version, name, and description). In either consent method, additional documents can be appended to the event by passing an array of consent document self-describing JSONs in the context argument.

The JSON schema for a consent document can be found here.

The fields of a consent document are:

NameDescriptionRequired?Type
idIdentifier for the documentYesString
versionVersion of the documentYesString
nameName of the documentNoString
descriptionDescription of the documentNoString

A consent document self-describing JSON looks like this:

{
"schema": "iglu:com.snowplowanalytics.snowplow/consent_document/jsonschema/1-0-0",
"data": {
"id": "1234",
"version": "5",
"name": "consent_document_name",
"description": "here is a description"
}
}

As an example, trackConsentGranted will store one consent document as a custom context:

snowplow('trackConsentGranted',
id: '1234',
version: '5',
name: 'consent_document',
description: 'a document granting consent',
expiry: '2020-11-21T08:00:00.000Z'
);

The method call will generate this event:

{
"e": "ue",
"ue_pr": {
"schema": "iglu:com.snowplowanalytics.snowplow/unstruct_event/jsonschema/1-0-0",
"data": {
"schema": "iglu:com.snowplowanalytics.snowplow/consent_granted/jsonschema/1-0-0",
"data": {
"expiry": "2020-11-21T08:00:00.000Z"
}
}
},
"co": {
"schema": "iglu:com.snowplowanalytics.snowplow/contexts/jsonschema/1-0-0",
"data": {
"schema": "iglu:com.snowplowanalytics.snowplow/consent_document/jsonschema/1-0-0",
"data": {
"id": "1234",
"version": "5",
"name": "consent_document",
"description": "a document granting consent"
}
}
}
}

GDPR context entity

Attach a context entity with the GDPR basis for processing and the details of a related document (e.g. a consent document) to all events which are fired after it is set.

It takes the following arguments:

NameDescriptionRequired?Type
basisForProcessingGDPR Basis for processingYesEnum String
documentIdID of a GDPR basis documentNoString
documentVersionVersion of the documentNoString
documentDescriptionDescription of the documentNoString
{
"e": "ue",
"ue_pr": {
"schema": "iglu:com.snowplowanalytics.snowplow/unstruct_event/jsonschema/1-0-0",
"data": {
"schema": "iglu:com.snowplowanalytics.snowplow/consent_granted/jsonschema/1-0-0",
"data": {
"expiry": "2020-11-21T08:00:00.000Z"
}
}
},
"co": {
"schema": "iglu:com.snowplowanalytics.snowplow/contexts/jsonschema/1-0-0",
"data": {
"schema": "iglu:com.snowplowanalytics.snowplow/consent_document/jsonschema/1-0-0",
"data": {
"id": "1234",
"version": "5",
"name": "consent_document",
"description": "a document granting consent"
}
}
}
}

The required basisForProcessing accepts only the following literals: consentcontractlegalObligationvitalInterestspublicTasklegitimateInterests - in accordance with the five legal bases for processing.

The GDPR context is enabled by calling the enableGdprContext method once the tracker has been initialized, for example:

snowplow('enableGdprContext', {
basisForProcessing: 'consent',
documentId: 'consentDoc-abc123',
documentVersion: '0.1.0',
documentDescription: 'this document describes consent basis for processing'
});

The schema is here.

Was this page helpful?