Programmatically Retrieving Data Subject Consent Choices

Background

DataGrail Consent can manage both a data subject's online tracking preferences as well as tracking that occurs in-app or via other marketing automation platforms and solutions like Segment or HubSpot.

When a data subject makes a consent choice, your development team can pick up this preference using the methods outlined below. From there, you can tie together this event with other customer identifiers you store to have a reference point for how to respect your customer's data sharing preferences across your entire application.

DataGrail will continuously report the preference of a data subject, using a unique device identifier, so your team can send this information to other downstream apps and services.

Need Something?

Our solution engineers are here to help! Let us know if you want more information on how to use this feature to integrate with other tools you use across your marketing stack.

Setting up callback functions

There are two different callback functions you can listen to as a browser events:

• initial_preference_callback: This returns any preferences set by the user as soon as the page loads.
• preference_callback: This returns any preferences set by the user after they have selected an action via the banner notice.

Registering a callback code sample:

<script>
  window.dgEvent = window.dgEvent || [];
  function sync_receive_prefs(preferences) {
    console.log("got sync preferences: " + JSON.stringify(preferences, null, 1));
  }

  window.dgEvent.push({
    event: "preference_callback",
    params: sync_receive_prefs
  });
</script>

Either function will run irrespective of the load order; for example, this script runs before the DataGrail Consent code (consent.js), it will still respond with any preference we have for that user/device.

It's also possible to do this with an async function:

<script>
  window.dgEvent = window.dgEvent || [];

  const async_receive_prefs = async function (preferences) {
    start = Math.floor(Date.now() / 1000)
    await new Promise(r => setTimeout(r, 2000));
    waited = Math.floor(Date.now() / 1000) - start
    console.log(`async preferences waited(${waited}s): ` + JSON.stringify(preferences, null, 1));
  };

  window.dgEvent.push({
    event: "preference_callback",
    params: async_receive_prefs
  });
</script>

Consent preferences provided by DataGrail

We will pass a Hash/Object structured like the following:

{
 "consentPreferences": {
  "cookieOptions": [
   {
    "gtm_key": "dg-category-essential",
    "isEnabled": true
   },
   {
    "gtm_key": "dg-category-marketing",
    "isEnabled": false
   },
   {
    "gtm_key": "dg-category-performance",
    "isEnabled": false
   },
   {
    "gtm_key": "dg-category-functional",
    "isEnabled": false
   }
  ],
  "isCustomized": true
 },
 "action": "essential_only",
 "uniqueID": "<customer uuid>.<user uuid>",
 "policyName": "default"
}

Key	Description
cookieOptions	Array of the data subject's preferences by category.
action	Action button selected via the site banner, which can be one of the following values: essential_only - Do not share information with non-essential services accept_all - Accepted sharing information with all services custom - Made specific preferences to certain categories of services GPC - Submitted using global privacy control signal (common with Brave users) DNT - Submitted using do not track signal (common with Firefox users)
uniqueID	Unique identifier DataGrail generates for each user's device visiting your site. We do not change this identifier by device
policyName	Policy applied for the data subject as set within the DataGrail Consent Management app
isCustomized	Legacy key; Will be removed in a future release