Create and publish a multi-regulation consent notice

This tutorial will walk you through the steps necessary to create a multi-regulation notice, modify its configuration, and publish it.

Please be aware that requests for multi-regulation notices specify the v:"2" header value; don't forget to include this in your API requests to the /widgets/notices and /widgets/notices/configs endpoints.

Create a consent notice

To create a consent notice, send a POST /widgets/notices request with the name of the notice to create and the ID of the organization that the notice belongs to:

const bent = require("bent");
const organizationId = "didomi";
const headers = {
  Authorization: `Bearer ${token}`,
  v: "2",
};

const client = {
  post: bent(
    "POST",
    "https://api.didomi.io/v1",
    "json",
    headers,
    201
  ),
};

(async () => {
  console.log(`Creating a notice for organization ${organizationId} ...`);

  const notice = await client.post("/widgets/notices", {
    organization_id: organizationId,
    name: "My consent notice",
  });

  console.log(`Notice with ID ${notice.id} created!`);
})();

The API will return a response similar to:

{
    "name": "My consent notice",
    "archived_at": null,
    "organization_id": "didomi",
    "id": "7wmRYUH6",
    "created_at": "2021-03-27T08:38:10.831Z",
    "updated_at": "2021-03-27T08:38:10.831Z",
    "version": 0
}

Modify the notice's draft multi-regulation configuration

The API automatically created a draft configuration when a notice was created. To update the notice configuration, you must first get the ID of the draft configuration and then modify that draft configuration.

Get the ID of the draft configuration

To get the ID of the draft configuration, get the list of all configurations:

const bent = require("bent");
const noticeId = "QdA3yxfi";
const BASE_URL = "https://api.didomi.io/v1";

const headers = {
  Authorization: `Bearer ${token}`,
  v: "2",
};

const client = {
  get: bent("GET", BASE_URL, "json", headers),
  patch: bent("PATCH", BASE_URL, "json", headers),
  post: bent("POST", BASE_URL, "json", headers, 201),
};

(async () => {
  console.log("Getting the latest draft config ...");

  // Get the Configuration related to our notice with deployed_at as NULL.
  const {
    data: [draftConfiguration],
  } = await client.get(
    `/widgets/notices/configs?notice_id=${noticeId}&deployed_at=null`
  );

  console.log(
    `A default notice has ${draftConfiguration.regulation_configurations.length} Regulation-Configurations`
  );
  // prints: A default notice has 3 Regulation-Configurations

  console.log(
    `A default notice has ${
      draftConfiguration.regulation_configurations.filter(
        (rc) => rc.regulation_id === "gdpr"
      ).length
    } GDPR related Regulation-Configurations`
  );
  // prints: A default notice has 3 GDPR related Regulation-Configurations

  const defaultGdprConfigurations =
    draftConfiguration.regulation_configurations.filter(
      (rc) => rc.regulation_id === "gdpr" && rc.is_default_regulation_config
    );

  console.log(
    `A regulation should only have 1 default configuration hence our Configuration is ${
      defaultGdprConfigurations.length === 1 ? "valid" : "invalid"
    }!`
  );
  // prints: A regulation should only have 1 default Regulation-Configuration hence our Configuration is valid!

  const italyOverride = draftConfiguration.regulation_configurations.find(
    (rc) =>
      rc.regulation_id === "gdpr" &&
      !rc.is_default_regulation_config &&
      rc.geo_locations.length === 1 &&
      rc.geo_locations[0] === "IT"
  );

  const franceOverride = draftConfiguration.regulation_configurations.find(
    (rc) =>
      rc.regulation_id === "gdpr" &&
      !rc.is_default_regulation_config &&
      rc.geo_locations.length === 1 &&
      rc.geo_locations[0] === "FR"
  );

  if (italyOverride && franceOverride) {
    console.log(
      "A default notice has overrides set up for France and Italy to comply with local requirements."
    );
  } else {
    throw new Error("Something went wrong :(");
  }
})();

The configuration is called "draft" because its deployed_at field is null which indicates that this configuration has not been published before and can be modified.

As we are working with a newly created notice in this tutorial, we can assume that it has a single associated configuration and that it is a draft. If you are working with an existing notice that might have been published before and would have multiple configurations, read our documentation to find the current draft documentation.

Modify the draft configuration

To modify the draft configuration, send a PATCH request with the updated configuration. In this example, we change the cross-regulation defaults for consent duration to 12 months and include CPRA as a targeted regulation for California, United States.

const bent = require("bent");
const organizationId = "<organizationId>";
const noticeId = "<noticeId>";
const BASE_URL = "https://api.didomi.io/v1";
const token = "<token>>"; // Get a token by authenticating in the API (https://developers.didomi.io/api/introduction/authentication)

const headers = {
  Authorization: `Bearer ${token}`,
  v: "2",
};

const client = {
  get: bent("GET", BASE_URL, "json", headers),
  patch: bent("PATCH", BASE_URL, "json", headers),
  post: bent("POST", BASE_URL, "json", headers, 201),
};

(async () => {
  console.log("Getting the latest draft config ...");

  let {
    data: [draftConfiguration],
  } = await client.get(
    `/widgets/notices/configs?notice_id=${noticeId}&deployed_at=null`
  );
  console.log("Patching consent duration to 6 months");

  draftConfiguration = await client.patch(
    `/widgets/notices/configs/${draftConfiguration.id}`,
    {
      consent_duration: 6,
      consent_duration_unit: "months",
    }
  );

  console.log(
    `The configuration has a consent duration of ${draftConfiguration.consent_duration} ${draftConfiguration.consent_duration_unit}`
  );
  // prints: The configuration has a consent duration of 6 months

  console.log("Enabling CPRA for California, United States");

  draftConfiguration.regulation_configurations.push({
    regulation_id: "cpra",
    is_default_regulation_config: true,
    geo_locations: ["US_CA"],
  });

  draftConfiguration = await client.patch(
    `/widgets/notices/configs/${draftConfiguration.id}`,
    draftConfiguration
  );

  // Check enabled regulations.
  const enabledRegulations = draftConfiguration.regulation_configurations
    .filter((rc) => rc.is_default_regulation_config)
    .map((rc) => rc.regulation_id);

  console.log(
    `The configuration has the following regulations enabled: ${enabledRegulations.join(
      ", "
    )}`
  );
  // prints: The configuration has the following regulations enabled: gdpr, cpra

  // Set IAB vendor 100mercis and tappx-Vzy7mget on CPRA configuration.
  let cpraConfiguration = draftConfiguration.regulation_configurations.find(
    (rc) => rc.is_default_regulation_config && rc.regulation_id === "cpra"
  );

  cpraConfiguration.config.app = {
    vendors: {
      include: ["100mercis", "tappx-Vzy7mget"],
    },
  };

  draftConfiguration = await client.patch(
    `/widgets/notices/configs/${draftConfiguration.id}`,
    draftConfiguration
  );

  cpraConfiguration = draftConfiguration.regulation_configurations.find(
    (rc) => rc.is_default_regulation_config && rc.regulation_id === "cpra"
  );

  console.log(
    `CPRA has the following vendors set: ${cpraConfiguration.config.app.vendors.include.join(
      ", "
    )}`
  );
  // prints: CPRA has the following vendors set: 100mercis, tappx-Vzy7mget
})();

Publish the notice

Now that our notice is configured as we want it to be, we need to publish it so that our modified configuration appears in the actual notice on the website or app.

To publish a notice, we need to create a new deployment for that notice.

It is not necessary to set the v:"2" header when deploying, the /widgets/notices/deployments endpoint does not require it.

const bent = require("bent");
const organizationId = "<organizationId>";
const noticeId = "<noticeId>";
const BASE_URL = "https://api.didomi.io/v1";
const token = "<token>"; // Get a token by authenticating in the API (https://developers.didomi.io/api/introduction/authentication)

const headers = {
  Authorization: `Bearer ${token}`,
  v: "2"
};

const client = {
  get: bent("GET", BASE_URL, "json", headers),
  post: bent("POST", BASE_URL, "json", headers, 201),
};

(async () => {
  console.log("Getting the latest draft config ...");

  const {
    data: [draftConfiguration],
  } = await client.get(
    `/widgets/notices/configs?notice_id=${noticeId}&deployed_at=null`
  );
  console.log("Deploying draft configuration");

  const response = await client.post("/widgets/notices/deployments", {
    notice_id: draftConfiguration.notice_id,
    production_config_id: draftConfiguration.id,
    organization_id: draftConfiguration.organization_id,
    message: "Enabled CPRA and deployed via the API"
  });

  console.log(`Your deployment is a ${response.status}!`);
  // prints: Your deployment is a success
})();

The production_config_id should be the ID of the draft config you are publishing. message is a text field that can be used to indicate information on what changes are included in your deployment.

The API responds with the status of your deployment:

{
    "message": "Description of changes included in my deployment",
    "notice_id": "7wmRYUH6",
    "production_config_id": "7bKP4CRr",
    "organization_id": "didomi",
    "status": "success",
    "status_message": null,
    "id": "itBtwnxM",
    "created_at": "2021-03-27T08:53:07.467Z",
    "updated_at": "2021-03-27T08:53:07.467Z",
    "version": 0
}

What's next?

The Didomi API allows managing all aspects of consent notices and their configurations. Read more about the entities to learn how to do more complex operations.

PreviousCreate and publish a consent noticeNextPrivacy widgets

Last updated