集成Platform Web SDK以处理客户同意数据

利用Adobe Experience Platform Web SDK,可检索由同意管理平台(CMP)生成的客户同意信号,并在发生同意更改事件时将其发送到Adobe Experience Platform。

SDK不会与任何现成的CMP进行接口。至于如何将SDK集成到您的网站,如何监听CMP中的同意更改,以及如何调用相应的命令,这将由您来决定。 本文档提供了有关如何将CMP与Platform Web SDK集成的一般指导。

先决条件

本教程假定您已确定如何在CMP中生成同意数据,并已创建一个数据集,其中包含符合Adobe标准或IAB透明度与同意框架(TCF)2.0标准的同意字段。 如果您尚未创建此数据集,请先参阅以下教程,然后再返回到本指南:

本指南遵循使用数据收集UI中的标记扩展设置SDK的工作流程。 如果您不想使用该扩展,并且希望在网站上直接嵌入SDK的独立版本,请参阅以下文档,而不是本指南:

本指南中的安装步骤需要对标记扩展以及它们在Web应用程序中的安装方式有一定的了解。 有关更多信息,请参阅以下文档:

设置数据流

为了使SDK将数据发送到Experience Platform,您必须首先配置数据流。 在数据收集UI的左侧导航中,选择​Datastreams

创建新数据流或选择要编辑的现有数据流后,选择​Adobe Experience Platform​旁边的切换按钮。 接下来,使用下面列出的值填写表单。

数据流字段
沙盒 平台sandbox的名称,其中包含设置数据流所需的流连接和数据集。
流入口 有效的流连接,用于Experience Platform。 如果您没有现有的流入口,请参阅有关创建流连接🔗的教程。
事件数据集 您计划使用SDK将事件数据发送到的XDM ExperienceEvent数据集。 虽然您需要提供事件数据集才能创建Platform数据流,但请注意,下游实施工作流中不接受通过事件发送的同意数据。
配置文件数据集 启用了Profile且包含您之前创建的🔗客户同意字段的数据集。

完成后,选择屏幕底部的​Save,然后继续按任何其他提示完成配置。

安装和配置平台Web SDK

按照上一节所述创建数据流后,必须配置最终将在您的网站上部署的Platform Web SDK扩展。 如果您的标记资产上未安装SDK扩展,请在左侧导航中选择​Extensions,然后选择​Catalog​选项卡。 然后,在可用扩展列表的Platform SDK扩展下选择​Install

配置SDK时,在​边缘配置​下,选择您在上一步中创建的数据流。

选择​Save​以安装该扩展。

创建数据元素以设置默认同意

安装SDK扩展后,您可以选择创建一个数据元素来表示用户的默认数据收集同意值(collect.val)。 如果您希望根据用户使用不同的默认值,例如pending(欧盟用户)和in(北美用户),则此选项会很有用。

在此用例中,您可以实施以下内容,以根据用户的区域设置默认同意:

  1. 确定Web服务器上的用户区域。
  2. 在网页上的script标记(嵌入代码)之前,渲染一个单独的script标记,该标记会根据用户的区域设置一个adobeDefaultConsent变量。
  3. 设置一个使用adobeDefaultConsent JavaScript变量的数据元素,并将此数据元素用作用户的默认同意值。

如果用户的区域由CMP确定,则可以改用以下步骤:

  1. 处理页面上的“CMP loaded”事件。
  2. 在事件处理程序中,根据用户区域设置一个adobeDefaultConsent变量,然后使用JavaScript加载标记库脚本。
  3. 设置一个使用adobeDefaultConsent JavaScript变量的数据元素,并将此数据元素用作用户的默认同意值。

要在数据收集UI中创建数据元素,请在左侧导航中选择​数据元素,然后选择​添加数据元素​以导航到数据元素创建对话框。

在此,必须基于adobeDefaultConsent创建JavaScript变量数据元素。 完成后,选择​保存

创建数据元素后,导航回Web SDK扩展配置页面。 在Privacy部分下,选择​由数据元素提供,然后使用提供的对话框选择之前创建的默认同意数据元素。

在您的网站上部署扩展

配置完该扩展后,即可将其集成到您的网站中。 有关如何部署更新的库内部版本的详细信息,请参阅标记文档中的发布指南

发出同意更改命令

将SDK扩展集成到网站后,您可以开始使用Platform Web SDK setConsent命令将同意数据发送到Platform。

重要

setConsent命令仅直接更新Profile存储区中的数据,而不会向数据湖发送任何数据。

在以下两种情况下,应在您的网站上调用setConsent:

  1. 在页面上(换言之,在每次加载页面时)加载同意时
  2. 作为检测同意设置更改的CMP挂接或事件侦听器的一部分
注意

有关Platform SDK命令的常见语法的介绍,请参阅正在执行命令的文档。

setConsent命令需要两个参数:

  1. 指示命令类型的字符串(在本例中为"setConsent"
  2. 包含单个数组类型属性的有效负荷对象:consentconsent数组必须至少包含一个对象,该对象为Adobe标准提供必需的同意字段。

以下示例setConsent调用中显示了Adobe标准的必需同意字段:

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"
      }
    }
  }]
});
负载属性 描述
standard 使用的同意标准。 对于Adobe标准,此值必须设置为Adobe
version standard下所示的同意标准的版本号。 要进行Adobe标准同意处理,必须将此值设置为2.0
value 客户更新的同意信息,作为XDM对象提供,该对象符合启用了用户档案的数据集同意字段的结构。
注意

如果您将其他同意标准与Adobe(例如IAB TCF)结合使用,则可以为每个标准向consent数组添加其他对象。 每个对象必须包含standardversionvalue的相应值,以表示同意标准。

以下JavaScript提供了一个函数示例,该函数用于处理网站上的同意首选项更改,该函数可用作事件侦听器或CMP挂接中的回调:

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

处理SDK响应

所有Platform SDK命令都返回指示调用是成功还是失败的承诺。 然后,您可以将这些响应用于其他逻辑,如向客户显示确认消息。 有关特定示例,请参阅执行SDK命令指南中处理成功或失败的部分。

使用SDK成功执行setConsent调用后,可以使用平台UI中的配置文件查看器来验证数据是否已登录到配置文件存储区。 有关更多信息,请参阅按标识浏览用户档案部分。

后续步骤

按照本指南,您已将Platform Web SDK扩展配置为将同意数据发送到Experience Platform。 有关测试实施的指导,请参阅要实施的同意标准文档:

在此页面上