Skip to content

Configuring the CMP

Configuring the CMP

The following section covers the main operations that can be performed through this API, such as creating and updating settings. However, because settings are a complex structure, in depth documentation about specific properties or use cases are documented in Configure the CMP via API page.

Creating new settings

To create new settings for an end-user, the only required parameters are the data controller (the owner of the website e.g. company name) and the language code which defines in which language the Usercentrics UI will be displayed later. For all other not given parameters a default value will be set.

Example Request

mutation {
  setting(
    dataController: "Webshop GmbH"
    language: "en"
  ) {
     settingsId
     language
  }
}

Example Response

{
  "data": {
    "setting": {
      "settingsId": "HkvOYLyME"
      "language": "en"
    }
  }
}

Creating new settings with custom categories

All Data Processing Services are displayed in a category. If you don’t specify a custom list of categories, the following default categories are created for you:

categorySlug (id) label (example english) isEssential
essential Essential true
functional Functional false
marketing Marketing false

However, it is also possible to define customized categories:

Example Request

mutation {
  setting(
    language: "en"
    categories: [
      {categorySlug:"essential", label:"Essentiell", isEssential: true}
      {categorySlug:"payment", label:"Payment Service", isEssential: true}
      {categorySlug:"marketing", label:"Marketing", isEssential: false}
    ]
  ) {
    settingsId
    categories  {
      categorySlug
    }
  }
}

Example Response

{
  "data": {
    "setting": {
      "settingsId": "PFij5LnJo",
      "categories": [
        {
          "categorySlug": "essential"
        },
        {
          "categorySlug": "payment"
        },
        {
          "categorySlug": "marketing"
        }
      ]
    }
  }
}

Creating a setting for a specific legislation

Settings can be set up for specific use cases specifying a "setting template" (Not to be confused with a Consent Template, which represents Data Processing Service (DPS)). This template will ensure that correct default values are set to the new configuration. A template is a combination of a type of setting (web or app) and a legislation, e.g. TCF2, CCPA, etc. For example WEB_TCF2 or APP_CCPA. All possible values for templates are defined in the SettingTemplateString ENUM, which also indicates the legislations supported. Choosing a WEB_* template will apply default texts targeted for the web platform, while APP_* templates will apply default texts rephrased to better fit the mobile world. If no template is explicitly defined, the default value is set to WEB_GDPR.

Example Request

mutation {
  setting(
    dataController: "Webshop GmbH"
    language: "en"
    options: {
      template: WEB_TCF2
    }
  ) {
     settingsId
     tcf2Enabled
  }
}

Example Response

{
  "data": {
    "setting": {
      "settingsId": "XYZ",
      "tcf2Enabled": true
    }
  }
}

Updating settings

The operation to update a setting is the same one used to create new settings, the only difference is that you provide an existing settingsId as an additional input parameter.

Example Request

mutation {
  setting(
    language: "de"
    settingsId: "HkvOYLyME"
    firstUserInteraction: STANDARD_BANNER
    consentTemplates: [
      {
        templateId: "S1pcEj_jZX"
        version: "1.2.3"
        categorySlug: "essential"
      }
    ]
  ) {
    settingsId
  }
}

Example Response

{
  "data": {
    "setting": {
      "settingsId": "HkvOYLyME"
    }
  }
}

Reminder
As described in the introduction, please be reminded to the “state-machine behavior” of GraphQL. For all complex types like consentTemplates, categories, etc. all non-mentioned elements will be removed from the Setting!

Adding vendors to TCF settings

The Global Vendors List (GVL) can be found here. Additional information about vendors listed in the main list is hosted here.

Once the GVL has been inspected and the relevant vendors for your setting found, you can add them to the list through the setting mutation while creating a setting as described above or while updating it:

Example Request

mutation {
  setting(
    dataController: "Webshop GmbH"
    language: "en"
    options: {
      template: WEB_TCF2
    },
    tcf2: {
      selectedVendorIds: [4]
    }
  ) {
     settingsId
     tcf2Enabled
     tcf2 {
       selectedVendorIds
     }
  }
}

Example Response

{
  "data": {
    "setting": {
      "settingsId": "XYZ",
      "tcf2Enabled": true,
      "tcf2": {
        "selectedVendorIds": [ 4 ]
      }
    }
  }
}

Enabling multiple languages

The default CMP language is English ("en"). The property languagesAvailable explicitly defines in which languages the CMP will be shown to the end user. The language switch will only show the languages which are configured in languagesAvailable. The property editableLanguages defines languages that you can configure, but are not visible to the end user.

Both properties can be configured while creating or updating a setting.

Example Request

mutation {
  setting(
    language: "de",
    editableLanguages: ["en", "de"],
    languagesAvailable: ["en", "de"], # <---- enable english and german
    bannerMessage: "Das ist ein Beispiel"
  ) {
    settingsId
    editableLanguages
    languagesAvailable
    bannerMessage
  }
}

Example Response

{
  "data": {
    "setting": {
       "settingsId": "XYZ",
       "editableLanguages": [
         "en",
         "de"
       ],
       "languagesAvailable": [
         "en",
         "de"
       ],
       "bannerMessage": "Das ist ein Beispiel"
    }
  }
}

Adjusting setting styles

This operation modifies the styles of a setting. The language parameter is mandatory, the changes are already propagated to all language documents.

Example Request

mutation {
    setting(
       settingsId: "8yKTozwk",
       language: "en",
       styles: {
        btnAcceptBgColor: "123642", # change accept button background color
        cornerModalHeaderBgColor: "444444" # change the modal header background color
       }
    ) {
      styles{
          btnPrivacyButtonActiveSize
          btnDenyBgColor
          btnAcceptBgColor
          cornerModalHeaderBgColor
      }
     }
}

Example Response

{
  "data": {
    "setting": {
      "styles": {
        "btnPrivacyButtonActiveSize": 100,
        "btnDenyBgColor": "3ba1db",
        "btnAcceptBgColor": "123642",
        "cornerModalHeaderBgColor": "444444"
      }
    }
  }
}

Updating a text in a specific field for different languages

The process described below is the most up-to-date and recommended method. It incorporates a more flexible approach that performs better and allows multiple languages to be adjusted simultaneously. Please use this process for the best results.

The setSettingTranslations operation updates the values of multiple fields and languages at the same time for a setting.

  • settingsId indicates in which setting the translations should be applied;
  • toPreview indicates if the changes would only apply to preview(true) or to both live and preview(false);
  • translations it is object stores translations for multiple languages. Each top-level property represents a language (e.g., en, de), and within each language, the structure mirrors the translatable settings fields, mapping each field to its corresponding translation;

Example Request 

mutation {
  setSettingTranslations(
    settingsId: "settingsId"
    toPreview: false
    translations: {
      en: { labels: { btnDeny: "test-btn-deny-label-en" } }
      de: { labels: { btnDeny: "test-btn-deny-label-de" } }
    }
  ) {
    language
    labels {
      btnDeny
    }
  }
}

Example Response 

{
  "data": {
    "setSettingTranslations": [
      {
        "language": "en",
        "labels": {
          "btnDeny": "test-btn-deny-label-en"
        }
      },
      {
        "language": "de",
        "labels": {
          "btnDeny": "test-btn-deny-label-de"
        }
      }
    ]
  }
}

⚠️ Warning: Deprecated Process

The process described below is deprecated and has been replaced by the new process documented above. Future updates may remove it or make it unsupported. Please use the recommended process above instead.

The setTranslationForSettingsField operation updates the value of a specific field in a setting for different languages without automatic translation.

  • parentField indicates the first level of the property to be updated. e.g. categories.

    Some few root-level fields are allowed to be updated directly, in that case, the parentField should be "”.

  • childField indicates the second level of the property to be updated (a sub-field of the parent field). e.g. description.
  • childId must be provided in the childField happens to be an array. It will be used do identify which element in the array must be updated. Example Requests

    Update label translations in English and German ("en" and "de")

mutation {
  setTranslationForSettingsField(
    parentField: "labels"
    childField: "btnDeny"
    settingsId: "HkvOYLyME"
    childId: null
    translation: { en: "Labels btnDeny message in English", de: "Labels btnDeny Nachricht auf Deutsch" }
  ) {
    settingsId
    language
    version
    labels {
      btnDeny
    }
  }
}

Update a specific template (with exampleTemplateId) description in consentTemplated in English and German ("en" and "de")

mutation {
  setTranslationForSettingsField(
    parentField: "consentTemplates"
    childField: "description"
    settingsId: "HkvOYLyME"
    childId: "exampleTemplateId"
    translation: { en: "Description", de: "Beschreibung" }
  ) {
    settingsId
    language
    version
    consentTemplates {
      templateId
      description
    }
  }
}

Update bannerMessage only in German ("de")

mutation {
  setTranslationForSettingsField(
    settingsId: "HkvOYLyME",
    parentField: "",
    childField: "bannerMessage",
    translation: {
      de: "Banner Nachricht auf Deutsch"
    }) {
      settingsId
      bannerMessage
      language
    }
}

Example Response

{
  "data": {
    "setTranslationForSettingsField": [
      {
        "settingsId": "HkvOYLyME",
        "bannerMessage": "Banner Nachricht auf Deutsch",
        "language": "de"
      },
      {
        "settingsId": "HkvOYLyME",
        "bannerMessage": "",
        "language": "en"
      }
    ]
  }
}

Providing setting access to other users

Adding users to a setting enables them to log into Admin Interface and configure the CMP on their own.

Important
Please be aware that the API User is listed within the users property value per default. If the API User is removed, access to that Setting via API is lost.
API Users can be recognized by the "#" in their account. The API User is added when the Setting was created via API. The Text after the "#" depends on the "user"-String used during Authentication.

Example Request

This request adds two new users to the setting (personA and personB) while still keeping access to the API User (testpartner#user123)

mutation {
  setting(language: "en", users: ["testpartner#user123","personA@customer.com","personB@customer.com"]) {
    settingsId
    users
  }
}

Example Response

{
  "data": {
    "setting": {
      "settingsId": "HkvOYLyME",
      "users": [
        "testpartner#user123"
        "personA@customer.com"
        "personB@customer.com"
      ]
    }
  }
}

Listing available Data Processing Services (Templates)

Example Request

query {
  consentTemplates {
    templateId
    version
    dataProcessors
  }
}

Example Response

{
  "data": {
    "consentTemplates": [
      {
        "templateId": "S1pcEj_jZX",
        "version": "8.2.1",
        "dataProcessors": [
          "Google Maps"
        ]
      },
      {
        "templateId": "S1_9Vsuj-Q",
        "version": "8.2.1",
        "dataProcessors": [
          "Google AdWords"
        ]
      }
    ]
  }
}

Listing settings accessible to the authenticated user

The settings query can list all settings objects that the user has read access to.

Example Request

query {
  settings {
    settingsId
    language
    firstUserInteraction
    consentTemplates {
      template {
        templateId
        dataProcessors
      }
    }
  }
}

Example Response

{
  "data": {
    "settings": [
      {
        "settingsId": "HkvOYLyME",
        "language": "en",
        "consentTemplates": [
          {
            "template": {
              "templateId": "S1pcEj_jZX",
              "dataProcessors": [
                "Google Maps"
              ]
            }
          },
          {
            "template": {
              "templateId": "S1_9Vsuj-Q",
              "dataProcessors": [
                "Google AdWords"
              ]
            }
          }
        ]
      },
      {
        "settingsId": "HkvOYLyME",
        "language": "de",
        "consentTemplates": [
          {
            "template": {
              "templateId": "S1pcEj_jZX",
              "dataProcessors": [
                "Google Maps"
              ]
            }
          },
          {
            "template": {
              "templateId": "S1_9Vsuj-Q",
              "dataProcessors": [
                "Google AdWords"
              ]
            }
          }
        ]
      }
    ]
  }
}

Fetching a specific setting by settingsId

If you know the settingsId and language of the setting you want to retrieve, you can use the setting (singular) endpoint instead. This endpoint behaves exactly like the settings (plural) endpoint, but always returns exactly one setting instead of a list of settings and languages.

Retrieving the Usercentrics CMP script tag

You can find more information on the latest Usercentrics CMP script tag for your customers in Browser CMP.

Accessing the Usercentrics Admin Interface

If you want to allow your customers to access their CMP via Usercentrics Admin Interface, please follow the below instructions to give the best experience to your customers.

  • Add the Users and Emails that shall get access
  • Set the correct Price Package Id: Price Packages
  • Specify the Domains on which the CMP will be integrated: Domain Whitelisting
  • Activate the latest CMP Version (V2) of the Admin Interface: Set property selectedSettingsAppVersion:V2
  • Assign a Data Controller who manages this configuration: Data Controller

Assigning a setting to a company

The operation attachSettingToCustomer attaches an existing setting to a Company/Customer provided both ids

Example Request

query {
  attachSettingToCustomer(customerId: "NxoH8s-Uy", settingsId: "HkvOYLyME")
}

Example Response

{
  "data": {
    "attachSettingToCustomer": true
  }
}

Removing a setting from given company

(does not delete the setting itself)

The operation detachSettingFromCustomer removes an existent setting from a company/customer provided both ids.

Example Request

query {
  detachSettingFromCustomer(customerId: "NxoH8s-Uy", settingsId: "HkvOYLyME")
}

Example Response

{
  "data": {
    "detachSettingFromCustomer": true
  }
}

Deleting settings

The operation deleteSetting can be used to delete a setting. The settingsId is mandatory.

Example Request

mutation {
  deleteSetting (settingsId: "HkvOYLyME")
}

Example Response

{
  "data": {
    "deleteSetting": "setting deleted successfully",
  }
}