Treasure Data JavaScript Consent Extension

Treasure Data JavaScript Consent Extension (TD JS Consent Extension) is a set of APIs that implement consent management solutions on the client side. It allows the TD customers to define categories of data use as well as different context for consent collection. The Consent Extension also empowers website’s visitors to control and customize their consent preferences for how data should be collected about them. They can choose to opt out entirely or selectively opt out of data collection in specific context if they don’t consent to the purpose of data use

Context and Consent

Treasure Data JavaScript Consent Extension has two concepts: Context and Consent that allows you to define the consent information for your website.

Context defines general information such as your brand, your domain, what type of consent collection. These information let you know that in which context user has agreed or disagreed with the consents. Each context consists the following fields:

brand : your company’s brand name
domain_name : website domain name that’s hosting the brand content as well as the TD-JS SDK
collection_type : different types of collection context, for example the consent collection context can be at the shopping cart page, a web form, or for the whole website.
collection_point_id : the identifier for each collection point you can pass in from other system. For example, if the collection context is a shopping cart page, you can use the shopping cart transaction id for this collection _ point _ id.
context_id : a auto-generated id for each context

Consent defines the semantics of a consent given by the consumer. Each consent consists the following fields:

purpose : category of data use
status : consent status, either given or refused or notgiven
datatype : a personal data type
context_id : context that the consent belongs to
identifier : user identifier
expiry_date : when the consent expires

The context and the purpose make the consent unique, so it could be used for filtering, querying for consented data.

Examples of context and consent

Copy

Copied

// Context
{
  brand: 'A brand',
  domain_name: 'abrand.com',
  collection_type: 'shopping_cart',
  collection_point_id: 'shopping_trnx_id',
  context_id: 'xxxxxxxxxx'
}

// Consent
{
  purpose: 'analytics',
  status: 'given',
  datatype: 'Purchase',
  context_id: 'xxxxxxxxxx',
  identifier: 'client id',
  expiry_date: 'YYYY-MM-DD'
}

Usage

Configurations

The configuration is setup along with the TD JavaScript SDK initialization.

Copy

Copied

var td = new Treasure({
  database: 'database',
  writeKey: '1/xxxxxxxxxx',
  host: 'in.treasuredata.com',
  consentManager: {
    storageKey: 'storage key',
    successConsentCallback: function () {},
    failureConsentCallback: function () {},
    expiredConsentsCallback: function () {},
    consentTable: 'consent_table_name',
    contextTable: 'context_table_name',
    issuer: 'name of the consent management platform',
    dateFormat: 'YYYY-MM-DD'
  }
})

Parameters:

storageKey : String (optional) - Name of the local storage. Default: td _ consent _ preferences
consentTable : String (optional) - Name of the consent table. Default: td _ cm _ consent
contextTable : String (optional) - Name of the context table. Default: td _ cm _ context
issuer : String (optional) - Name of the consent management platform. Default: treasuredata
dateFormat : String (optional) - Date format string. Default: YYYY-MM-DD
successConsentCallback : Function (optional) - Successful saving consent callback
failureConsentCallback : Function (optional) - Failed to save consent callback
expiredConsentsCallback : Function (optional) - Expired consent callback

Every time when a page is loaded, TD JS Consent Extension will check the consent expiry date and if there’s any expired consent, then the expiredConsentCallback is triggered. It also updates status of the expired consent to expired

Date format

Internally, we use dayjs to handle date formatting, so the date format string should follow this document string-format

Full example of using TD JS Consent Extension to create default consent preferences for the consumer.

Copy

Copied

function successCallback (preferences) {
  if (preferences['analytics'].status === 'given') {
    td.setSignedMode()
    td.unblockEvents()
  } else if (preferences['analytics'].status === 'refused') {
    td.setAnonymousMode()
    td.blockEvents()
  }

  td.trackPageview()
}

var td = new Treasure({
  database: 'database',
  writeKey: '1/xxxxxxxxxx',
  host: 'in.treasuredata.com',
  consentManager: {
    storageKey: 'consent_preferences',
    successConsentCallback: successCallback
  }
})

// we setup contexts and consents when the TD JavaScript SDK is ready
td.ready(function () {
  // check if the preferences exists
  // otherwise don't do the setup again.
  if (!td.getPreferences()) {
    var contextId = td.addContext({
      brand: 'A Brand',
      domain_name: 'abrand.com',
      collection_type: 'Whole website',
      collection_point_id: 'whole_website'
    })

    td.addConsents({
      analytics: {
        description:
          'We use browser cookies that are necessary for the site to work as intended.For example, we store your website data collection preferences so we can honor them if you return to our site. You can disable these cookies in your browser settings but if you do the site may not work as intended.',
        status: td.consentManager.states.GIVEN,
        datatype: 'Visits',
        context_id: contextId,
      }
    })

    contextId = td.addContext({
      brand: 'Treasure Data',
      domain_name: 'treasuredata.com',
      collection_type: 'Shopping Cart',
      collection_point_id: 'shopping_trnx_id'
    })

    td.addConsents({
      recommendations: {
        description: 'Description of the consent',
        status: td.consentManager.states.GIVEN,
        datatype: 'Purchases',
        context_id: contextId
      },
      storing: {
        description: 'Description',
        datatype: 'Purchases',
        status: td.consentManager.states.REFUSED,
        context_id: contextId
      }
    })
  }
})

// Later on, based on the user's interactions with your consent information
// you should save the preferences
td.saveContexts()
td.saveConsents()

addContext(context)

Adding context for consents, the context will be included when we send data to TD platform (event-collector). Users can specify their own context id otherwise a new context id will be generated.

Parameters:

context : Object (required) - Context information
- brand : String - brand name
- domain_name : String - domain name
- collection_type : String - consent collection type
- collection_point_id : String - consent collection point id
- context_id : String (optional) - Context Id
Return context id

Copy

Copied

sdk.addContext({
  brand: 'A Brand',
  domain_name: 'abrand.com',
  collection_type: 'shopping_cart',
  collection_point_id: 'shopping_trnx_id'
  context_id: 'uuid'
})

addConsents(consents)

Adding consents. For the consents that don’t have context ID, they will be added to a default context

Parameters:

consents : Object (required) - A map that contains multiple consent objects, each consent object has a key as consent’s purpose and a value as consent’s information
- consent : Object - Specific consent
- key : String - purpose of consent
- values : Object - consent information
  - description : String - Consent’s description
  - datatype : String - data type
  - status : String - Consent’s status (given | refused | notgiven). Default: notgiven
  - expiry_date : (String|Number|Date) - expiry date
  - context_id : String - Context Id

Copy

Copied

sdk.addConsents({
  'marketing': { // <--- purpose
    description: 'description of consent',
    datatype: 'Attibutes',
    status: 'given|refused',
    expiry_date: 'YYYY-MM-DD',
    context_id: 'context_id'
  },
  'storing': { // <--- purpose
    description: 'description',
    datatype: 'datatype',
    status: 'given|refused',
    expiry_date: 'YYYY-MM-DD',
    context_id: 'context_id'
  },
  'recommendations': { // <--- purpose
    description: 'description',
    datatype: 'datatype',
    status: 'given|refused',
    expiry_date: 'YYYY-MM-DD',
    context_id: 'context_id'
  }
)

saveContexts(success, error)

Save the contexts to the local storage and to the Treasure Data platform

Parameters:

success : Function (optional) - Callback for when saving the contexts successfully
error : Function (optional) - Callback for when saving the contexts unsuccessfully

Copy

Copied

function success () {
  // yay()
}

function error (err) {
  /**
  * err: { success: false, message: 'Timeout' }
  */
}

sdk.saveContexts(success, error)

saveConsents(success, error)

Save the consents to the local storage and to the Treasure Data platform

Parameters:

success : Function (optional) - Callback for when saving the consents successfully
error : Function (optional) - Callback for when saving the consents unsuccessfully

If you don’t specify the callbacks, the callbacks that are configured in the Configurations section above will be called.

Copy

Copied

function success (preferences) {
  // yay()
}

function error (err) {
  /**
  * err: { success: false, message: 'Timeout' }
  */
}

sdk.saveConsents(success, error)

getConsents()

Return list of consents

getContexts()

Return list of contexts

updateConsent(contextId, consentObject)

Update a specific consent

Parameters:

contextId : String (required) - Context Id
consentObject : Object (required) - Consent that you want to update

Copy

Copied

sdk.updateConsent('xxxxxx-context-id', {
  'recommendations': {
    status: 'refused'
  }
})

When you update a consent, only the updated consent is sent to the successConsentCallback after calling saveConsents

updateContext(contextId, values)

Update a specific context

Parameters:

contextId : String (required) - Context Id
values : Object (required) - Values of context that you want to update

Copy

Copied

sdk.updateContext('xxxxxx-context-id', {
  brand: 'Other brand',
  domain_name: 'otherdomain.com'
})

getConsentExpiryDate(contextId, consentPurpose)

Get expiry date for a specific consent

Parameters:

contextId : String (required) - Context Id
consentPurpose : String (required) - The consent’s purpose

Copy

Copied

sdk.getConsentExpiryDate('context_id', 'analytics')

getExpiredConsents()

Returns expired consents

Add-on Consent UIs

In addition to the consent extension, we also provide add-on UIs (a banner and a webform) as an example of how we can use a custom UI with TD JavaScript SDK Consent Extension. For more information: Treasure Data Consent UIs