Integrate the Platform Web SDK to process customer consent data

The Adobe Experience Platform Web SDK allows you to retrieve customer consent signals generated by Consent Management Platforms (CMPs) and send them to Adobe Experience Platform whenever a consent-change event occurs.

The SDK does not interface with any CMPs out of the box. It is up to you to determine how to integrate the SDK into your website, listen for consent changes in the CMP, and call the appropriate command. This document provides general guidance on how to integrate your CMP with the Platform Web SDK.

Prerequisites

This tutorial assumes that you have already determined how to generate consent data within your CMP, and have created a dataset containing consent fields that conform to the Adobe standard or the IAB Transparency and Consent Framework (TCF) 2.0 standard. If you have not created this dataset yet, refer to the following tutorials before returning to this guide:

This guide follows the workflow for setting up the SDK using the tag extension in the Data Collection UI. If you do not want to use the extension and would prefer to directly embed the standalone version of the SDK on your site, please refer to the following docs instead of this guide:

The installation steps in this guide require a working understanding of tag extensions and how they are installed in web applications. Refer to the following documentation for more information:

Set up a datastream

In order for the SDK to send data to Experience Platform, you must first configure a datastream. In the Data Collection UI, select Datastreams in the left navigation.

After creating a new datastream or selecting an existing one to edit, select the toggle button next to Adobe Experience Platform. Next, use the values listed below to complete the form.

Datastream field Value
Sandbox The name of the Platform sandbox that contains the required streaming connection and datasets to set up the datastream.
Streaming Inlet A valid streaming connection for Experience Platform. See the tutorial on creating a streaming connection if you do not have an existing streaming inlet.
Event Dataset An XDM ExperienceEvent dataset that you plan on sending event data to using the SDK. While you are required to provide an event dataset in order to create a Platform datastream, please note that consent data sent via events is not honored in downstream enforcement workflows.
Profile Dataset The Profile-enabled dataset with customer consent fields that you created earlier.

When finished, select Save at the bottom of the screen and continue following any additional prompts to complete the configuration.

Install and configure the Platform Web SDK

Once you have created a datastream as described in the previous section, you must then configure the Platform Web SDK extension that you will ultimately deploy on your site. If you do not have the SDK extension installed on your tag property, select Extensions in the left navigation, followed by the Catalog tab. Then, select Install under the Platform SDK extension within the list of available extensions.

When configuring the SDK, under Edge Configurations, select the datastream you created in the previous step.

Select Save to install the extension.

With the SDK extension installed, you have the option to create a data element to represent the default data collection consent value (collect.val) for your users. This can be useful if you want to have different default values depending on the user, such as pending for European Union users and in for North American users.

In this use case, you could implement the following to set default consent based on the user’s region:

  1. Determine the user’s region on the web server.
  2. Before the script tag (embed code) on the web page, render a separate script tag that sets an adobeDefaultConsent variable based on the user’s region.
  3. Set up a data element that uses the adobeDefaultConsent JavaScript variable, and use this data element as the default consent value for the user.

If the user’s region is determined by a CMP, you can use the following steps instead:

  1. Handle the “CMP loaded” event on the page.
  2. In the event handler, set an adobeDefaultConsent variable based on the user’s region, and then load the tag library script using JavaScript.
  3. Set up a data element that uses the adobeDefaultConsent JavaScript variable, and use this data element as the default consent value for the user.

To create a data element in the Data Collection UI, select Data Elements in the left navigation, then select Add Data Element to navigate to the data element creation dialog.

From here, you must create a JavaScript Variable data element based on adobeDefaultConsent. Select Save when finished.

Once the data element is created, navigate back to the Web SDK extension config page. Under the Privacy section, select Provided by data element, and use the provided dialog to select the default consent data element you created earlier.

Deploy the extension on your website

Once you have finished configuring the extension, it can be integrated into your website. Refer to the publishing guide in the tags documentation for detailed information on how to deploy your updated library build.

Making consent-change commands

Once you have integrated the SDK extension into your website, you can start using the Platform Web SDK setConsent command to send consent data to Platform.

IMPORTANT

The setConsent command only updates data directly in the Profile store, and does not send any data to the Data Lake.

There are two scenarios where setConsent should be called on your site:

  1. When consent is loaded on the page (in other words, on every page load)
  2. As part of a CMP hook or event listener that detects changes in consent settings
NOTE

For an introduction to the common syntax for Platform SDK commands, see the document on executing commands.

The setConsent command expects two arguments:

  1. A string that indicates the command type (in this case, "setConsent")
  2. A payload object that contains a single array-type property: consent. The consent array must contain at least one object that provides the required consent fields for the Adobe standard.

The required consent fields for the Adobe standard are shown in the following example setConsent call:

alloy("setConsent", {
  consent: [{
    standard: "Adobe",
    version: "2.0",
    value: {
      collect: {
        val: "y"
      },
      share: {
        val: "y"
      },
      personalize: {
        content: {
          val: "y"
        }
      },
      metadata: {
        time: "2020-10-12T15:52:25+00:00"
      }
    }
  }]
});
Payload property Description
standard The consent standard being used. For the Adobe standard, this value must be set to Adobe.
version The version number of the consent standard indicated under standard. This value must be set to 2.0 for Adobe-standard consent processing.
value The customer’s updated consent information, provided as an XDM object that conforms to the structure of the Profile-enabled dataset’s consent fields.
NOTE

If you are using other consent standards in conjunction with Adobe (such as IAB TCF), you can add additional objects to the consent array for each standard. Each object must contain appropriate values for standard, version, and value for the consent standard they represent.

The following JavaScript provides an example of a function that handles consent preference changes on a website, which can used as a callback in an event listener or a CMP hook:

var setConsent = function () {

  // Retrieve the current consent data.
  var categories = getConsentData();

  // If the script is running on a consent change, generate a new timestamp.
  // If the script is running on page load, set the timestamp to when the consent values last changed.
  var now = new Date();
  var collectedAt = consentChanged ? now.toISOString() : categories.collectedAt;

  //  Map the consent values and timestamp to XDM
  var consentXDM = {
    collect: {
      val: categories.collect !== -1 ? "y" : "n"
    },
    personalize: {
      content: {
        val: categories.personalizeContent !== -1 ? "y" : "n"
      }
    },
    share: {
      val: categories.share !== -1 ? "y" : "n"
    },
    metadata: {
      time: collectedAt
    }
  };

  // Pass the XDM object to the Platform Web SDK
  alloy("setConsent", {
    consent: [{
      standard: "Adobe",
      version: "2.0",
      value: consentXDM
    }]
  });
});

Handling SDK responses

All Platform SDK commands return promises that indicate whether the call succeeded or failed. You can then use these responses for additional logic such as displaying confirmation messages to the customer. See the section on handling success or failure in the guide on executing SDK commands for specific examples.

Once you have successfully made setConsent calls with the SDK, you can use the profile viewer in the Platform UI to verify whether data is landing in the Profile store. See the section on browsing profiles by identity for more information.

Next steps

By following this guide, you have configured the Platform Web SDK extension to send consent data to Experience Platform. For guidance on testing your implementation, refer to the documentation for the consent standard that you are implementing:

On this page