Consent Callbacks

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.

Callback Setup

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

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

Example Consent Callbacks

Consent Callback examples for common web apps and tracking services are listed below.

Facebook Pixel

If your Facebook Pixel is not managed with Google Tag Manager or DataGrail's ScriptControl, you can do so with a callback function. With this implementation, you can leave the script running, but control the pixel opt-out via the Facebook Pixel GDPR support and a callback.

Here's some sample code:

<!-- Facebook Pixel Code -->
<script>
  !function(f,b,e,v,n,t,s)
  {if(f.fbq)return;n=f.fbq=function(){n.callMethod?
  n.callMethod.apply(n,arguments):n.queue.push(arguments)};
  if(!f._fbq)f._fbq=n;n.push=n;n.loaded=!0;n.version='2.0';
  n.queue=[];t=b.createElement(e);t.async=!0;
  t.src=v;s=b.getElementsByTagName(e)[0];
  s.parentNode.insertBefore(t,s)}(window, document,'script',
  'https://connect.facebook.net/en_US/fbevents.js');

  // NOTE: do not call fbq('init', '{pixel-id-goes-here}')
  // outside of the `init_fb_prefs` function.

  window.dgEvent = window.dgEvent || [];
  function fb_prefs(preferences) {
    if (window.DG_BANNER_API.categoryEnabled('marketing')) {
      fbq('consent', 'grant');
    } else {
      fbq('consent', 'revoke');
    }
  }
  function init_fb_prefs(preferences) {
    if (window.DG_BANNER_API.categoryEnabled('marketing')) {
      fbq('consent', 'grant');
      fbq('init', '{pixel-id-goes-here}');
      // optionally
      fbq('track', 'PageView');
    } else {
      fbq('consent', 'revoke');
      fbq('init', '{pixel-id-goes-here}');
    }
  }

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

We have provided two functions in this example, one that controls the pixel initialization and consent setting on every page load (init_fb_prefs) or one that controls the pixel consent setting when a consent preference is received (fb_prefs).

Shopify

DataGrail Consent interacts with the Shopify Privacy API, which passes on consent preferences in a format that pixels, audiences and checkout functionality must respect per Shopify's terms of service.

When a data subject makes a Consent choice, we emit preferences in the browser which can then be translated using a snippet of code to set the consent tracking settings per the API docs above.

It is up to the pixel vendors to respect and honor these tracking settings. While DataGrail can work with you to confirm that we are both accepting and passing preferences to Shopify correctly, we cannot reliably troubleshoot if pixels are behaving in a way that respects consent choices.

You must first make the following changes in Shopify:

1. Login to Shopify, select Settings, Customer privacy and then Cookie Banner.

2. Select the option to set custom banner regions, which offers you the ability to select the countries that you are letting Shopify know you wish to have managed consent.

   Since DataGrail works with a wide variety of countries and geographies, we recommend selecting every region available. This ensures that DataGrail controls the policies and behavior of consent through the DataGrail application.

3. Save your changes and then remove the cookie banner from being visible. This disables Shopify's built-in banner, but you still have the countries you select which inform Shopify to "await Consent" before proceeding with tracking.

With the banner deployed and ready to accept a consent choice, you now need to send this consent choice to Shopify so that it handles the behavior of pixels within Shopify. This is required if you are using built in tracking pixels from Facebook, TikTok, and other vendors with deep integrations into the product.

When a user makes a Consent choice with DataGrail, the preferences are saved and available as a callback function, which you can use as the basis for writing code to map DataGrail consent preference options to Shopify's tracking options. The code should call the setTrackingConsent API method with the mapped result.

Here's an example:

<script>
  window.dgEvent = window.dgEvent || [];
  function sync_receive_prefs(dgEventData) {
    const cookiePreferences = dgEventData?.consentPreferences?.cookieOptions;

    window.Shopify.loadFeatures(
      [
        {
          name: "consent-tracking-api",
          version: "0.1",
        },
      ],
      (error) => {
        if (error) {
          console.error("Error loading Shopify Customer API", error);
        }
        window.Shopify.customerPrivacy.setTrackingConsent(
          {
            preferences: true,
            analytics: window.DG_BANNER_API.categoryEnabled("performance"),
            marketing: window.DG_BANNER_API.categoryEnabled("marketing"),
            sale_of_data: window.DG_BANNER_API.categoryEnabled("marketing"),
          },
          (arg) => console.log("Consent captured", arg)
        );
      }
    );
  }

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

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

This code saves the consent preferences provided by a user, which is then mapped to the Shopify tracking consent preferences using the above API method.

To verify Shopify Consent preferences:

1. Confirm the values that have been set by DataGrail Consent, based on the Data Subject's policy settings or their explicit choices via the banner displayed.

window.DG_BANNER_API.getConsentPreferences()

{isCustomised: true, cookieOptions: Array(3)}
  cookieOptions: Array(3)
    0: {gtm_key: 'dg-category-performance', isEnabled: true}
    1: {gtm_key: 'dg-category-essential', isEnabled: true}
    2: {gtm_key: 'dg-category-marketing', isEnabled: false}
  length: 3

...

2. Confirm the value set for the Data Subject's consent preferences within Shopify. You can see the a false value for the dg-category-marketing or "Marketing" purpose has appropriately set the value for marketing and sale_of_data as no.

window.Shopify.customerPrivacy.currentVisitorConsent();

{marketing: 'no', analytics: 'yes', preferences: 'yes', sale_of_data: 'no'}