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 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 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 or Experience Platform 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.

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.

Create a data element to set default consent

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:

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

To create a data element in the 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 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.

The setConsent command performs two actions:

When to call setConsent

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

setConsent syntax

The setConsent command expects two arguments:

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"
      }
    }
  }]
});

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: