Map consents to cookie levels

Laws relating to personal data protection have come into effect in many places worldwide. In many cases, an essential step to comply with such regulations is to attain a consent agreement from an individual to store and process their personal data.

In some cases, when properly explained, consent for storing browser cookies in the visitor’s browser files can be sufficient for collecting and processing the data associated with those cookies’ functionality.

This example shows the process of creating a custom page in the Xperience administration interface that maps custom cookie levels to consents. With this page, editors can define which consents in the Data protection application are associated with specific cookie levels. This is a key step in creating a cookie-level configuration page, e.g. the cookie policy page on Kentico.com.

Before you start

This guide requires the following:

• Familiarity with C#, .NET Core, Dependency injection, and the MVC pattern.
• A running instance of Xperience by Kentico, preferably 29.6.1 or higher.
  Some features covered in the Training guides may not work in older versions.

The examples in this guide require that you:

• Have followed along with the samples from the earlier guides in the series.

Create the consents

First, open the Data protection application in the Configuration category of the administration interface for Xperience by Kentico, and create consents with the following properties:

1. Preference cookies consent
   1. New consent
      • Display name: Preference cookies
      • Code name: preference.cookies.consent
   2. Consent texts

      • Short text: Preference cookies help us remember changes and configurations you make on the site.

      • Full text: Preference cookies and the data you provide us make your work easier by, for example, remembering the language in which you want to display the pages, etc.

        

2. Analytical cookies consent
   1. New consent
      • Display name: Analytical cookies
      • Code name: analytical.cookies.consent
   2. Consent texts
      • Short text: Analytical cookies are used to gather usage data to measure and improve performance.
      • Long text: Analytical cookies and the data you provide us allow us to perform site usage analytics to measure and improve the site’s performance. For example, we know which pages are most frequently visited, which buttons users click, etc.
3. Marketing cookies consent
   1. New consent
      • Display name: Marketing cookies
      • Code name: marketing.cookies.consent
   2. Consent texts
      • Short text: Marketing cookies are used to provide relevant ads based on your activity.
      • Long text: Marketing cookies and the data you provide us allow us to link our website to third-party social media and advertising networks, such as Facebook or Google Ads. With this connection, we can present relevant ads outside our website.

Define the module

Create the class

Now that these consents exist, we can create a UI page for mapping them to cookie levels.

1. Open the Modules application in the administration interface for Xperience by Kentico, under the Development category.
2. Create a new module for adding custom pages to the Data protection application.

   1. Display name: Data protection customizations

   2. Pre-fill code name automatically: False (Disabled)

   3. Code name: TrainingGuides.DataProtectionCustomizations

      

3. On the Classes tab of this new module, create a new class.

   1. Display name: Cookie level consent mapping

   2. Namespace: TrainingGuides

   3. Name: CookieLevelConsentMapping

      

4. On the Database columns tab in this new class, add new fields with the following properties. These fields will determine which consent corresponds to each cookie level.

   1. Preference cookie consent field

      • Field name: PreferenceConsentCodeName

      • Data type: Object code names

      • Required: False (Disabled)

        

   2. Analytical cookie consent field

      • Field name: AnalyticalConsentCodeName
      • Data type: Object code names
      • Required: False (Disabled)

   3. Marketing cookie consent field

      • Field name: MarketingConsentCodeName
      • Data type: Object code names
      • Required: False (Disabled)

   4. Guid field

      • Field name: CookieLevelConsentMappingGuid
      • Data type: Unique identifier (GUID)
      • Required: True (Enabled)

Add the UI form

Switch to the UI forms tab of the class.

1. Populate the following properties accordingly:

   • Form display name: Cookie level consent mapping

   • Pre-fill code name automatically: False (Disabled)

   • Form name: CookieLevelConsentMapping

     

2. Save the form, and switch to the Fields tab.
3. Create a field for each previously specified consent columns with the following properties:
   • Form component: Object code names
   • Initial value: Select
   • Object type: CMS.Consent
   • Maximum items: 1
4. The fields should have the following Field caption values, respectively:
   • Preference cookies consent (level 2)
   • Analytical cookies consent (level 3)
   • Marketing cookies consent (level 4)

Generate the code

Next, designate code settings for the class to make it more compatible with other features.

1. Switch to the Code tab of the class.

2. Set the Object type to TrainingGuides.CookieLevelConsentMapping.

3. Set the Display name column to CookieLevelConsentMappingID, and set Code name column and GUID column to CookieLevelConsentMappingGuid.

4. Leave all the other properties un-set. 

   Readable names

   Typically, columns that hold human-readable data are used for Display names and code names of custom objects. This helps the people managing the objects find them in object listings and query them easily.

   However, in this case, there is only going to be a single entry for this class, so there will be no listing page. There is no need for the class to have a readable display name because it is never used.

   

This completes the administration interface setup for the class, so now the code can be generated.

Now, you can generate a code file for the custom class as described on this page.

1. Switch the command line to the TrainingGuides.Web directory.

2. Run the --kxp-codegen tool, setting the location to the TrainingGuides.Entities project and include only the CookieLevelConsentMapping class.

   CMD

   Copy

   
   
    dotnet run -- --kxp-codegen --type "Classes" --location "../TrainingGuides.Entities/{type}/{name}" --with-provider-class True --include "TrainingGuides.CookieLevelConsentMapping"
   
    

   This will generate three code files in the TrainingGuides.Entities/Classes/CookieLevelConsentMapping folder. 

   If you use a script to automate code generation as described in this guide, use the --include and --exclude parameters on multiple commands to generate classes that require dedicated provider classes separately from those that do not.
   1. CookieLevelConsentMappingInfo.generated.cs is the info class containing the definition for objects of this type.
   2. CookieLevelConsentMappingInfoProvider.generated.cs is the provider class, which has methods to interface with the database and perform CRUD operations on data.
   3. ICookieLevelConsentMappingInfoProvider.generated.cs is an interface that allows the provider to be injected with dependency injection.

3. Add a subfolder named Overrides to the ~/Classes folder of the TrainingGuides.Entities project.

4. Create a partial class for CookieLevelConsentMapping and enable continuous integration.

   Partial class

   Continuous Integration could be enabled by modifying the TYPEINFO declaration in the generated class. However, this separate partial class ensures that the change will not be overwritten next time the code is generated.

   C#

   CookieLevelConsentMappingInfoOverride.cs

   Copy

   
   
    namespace TrainingGuides.DataProtectionCustomizations;
   
    public partial class CookieLevelConsentMappingInfo
    {
        static CookieLevelConsentMappingInfo()
        {
            TYPEINFO.ContinuousIntegrationSettings.Enabled = true;
        }
    }
   
    

   This configuration allows the cookie-level consent mapping to be shared among developers by including serialized data in source control.

Add a page to the UI

Set up the project

Now that the class, form, and files are in place, we can integrate them into the UI.

1. Create a new Class Library project targeting your version of .NET under the TrainingGuides solution. Name it TrainingGuides.Admin.

2. Install the Kentico.Xperience.Admin and Kentico.Xperience.Core NuGet packages for the project. 

   Make sure to choose package versions that match the project’s version, indicated by the version of the Kentico.Xperience.WebApp package in the primary web project, and the value of the CMSDBVersion settings key in the CMS_SettingsKey table of the database.

3. Add a reference from the TrainingGuides.Admin project to the TrainingGuides.Entities project, and a reference from the TrainingGuides.Web project to the TrainingGuides.Admin project.

4. Add the assembly attribute to the TrainingGuides.Admin.csproj file:

...
<ItemGroup>
    <AssemblyAttribute Include="CMS.AssemblyDiscoverableAttribute">
    </AssemblyAttribute>
</ItemGroup>
...

Add the page

1. Add a folder called Pages to the TrainingGuides.Admin project, and create a new class file called CookieLevelConsentMappingPage.cs within. This page will be used to edit objects of the CookieLevelConsentMapping class.
   • Make the class inherit from InfoEditPage<CookieLevelConsentMappingInfo>. (You can find out more information about editing UI pages in the documentation.)
2. Register the page as a child of the DataProtectionContentLanguage page in the administration interface.
   1. Set the slug property to cookielevelconsentmapping, so that the URL of the page in the admin UI clearly indicates its purpose.
   2. Assign the Edit template, so that Xperience knows this page is used to edit objects of the CookieLevelConsentMapping type.
   3. Set the page order of UIPageOrder.First + 1, so that it is the second page after the Consents listing page.
3. Override the ObjectId property of the InfoEditPage class, making sure that its get accessor will either:

   • Return the ID of the first available CookieLevelConsentMappingInfo object,
     or

   • Create and save a new CookieLevelConsentMappingInfo object if none exists.

     Overriding the ObjectId property ensures that only one object of the CookieLevelConsentMapping type will ever exist, assuming no additional code to create them is added.

4. Override the ConfigurePage method and set PageConfiguration.UIFormName to the CookieLevelConsentMapping form codename before calling base.

using TrainingGuides.Admin.Pages;
using TrainingGuides.DataProtectionCustomizations;
using Kentico.Xperience.Admin.Base;
using Kentico.Xperience.Admin.Base.Forms;
using Kentico.Xperience.Admin.DigitalMarketing.UIPages;

[assembly: UIPage(
    parentType: typeof(DataProtectionContentLanguage),
    slug: "cookie-level-consent-mapping",
    uiPageType: typeof(CookieLevelConsentMappingPage),
    name: "Cookie level consent mapping",
    templateName: TemplateNames.EDIT,
    order: UIPageOrder.First + 1)]

namespace TrainingGuides.Admin.Pages;

internal class CookieLevelConsentMappingPage : InfoEditPage<CookieLevelConsentMappingInfo>
{
    private readonly ICookieLevelConsentMappingInfoProvider cookieLevelConsentMappingInfoProvider;

    public CookieLevelConsentMappingPage(IFormComponentMapper formComponentMapper, IFormDataBinder formDataBinder,
    ICookieLevelConsentMappingInfoProvider generalSettingsInfoProvider) : base(formComponentMapper, formDataBinder)
    {
        cookieLevelConsentMappingInfoProvider = generalSettingsInfoProvider;
    }


    public override int ObjectId
    {
        get
        {
            var mappings = GetOrCreateMappings();
            return mappings.CookieLevelConsentMappingID;
        }
        set => throw new InvalidOperationException("The $ObjectId value cannot be set.");
    }


    public override Task ConfigurePage()
    {
        PageConfiguration.UIFormName = "cookielevelconsentmapping";

        return base.ConfigurePage();
    }


    private CookieLevelConsentMappingInfo GetOrCreateMappings()
    {
        var item = cookieLevelConsentMappingInfoProvider.Get()?.FirstOrDefault();

        if (item == null)
        {
            item = new CookieLevelConsentMappingInfo
            {
                CookieLevelConsentMappingGuid = Guid.NewGuid()
            };
            cookieLevelConsentMappingInfoProvider.Set(item);
        }

        return item;
    }
}

When you rebuild the solution, you will see a new UI page in the Data protection application. Editors can use this page to map consents to the Preference, Analytical, and Marketing levels.

Map the consents

The new page can be used to save cookie consent mappings.

1. Navigate to the new page under the Cookie level consent mapping tab of the Data protection application in the Xperience administration interface.
2. Select the corresponding consent, created in previous steps, for each cookie level.

Now, the mapping can be retrieved using the provider classes saved earlier in the guide. 

What’s next?

The next guide in this series will show you how to create a cookie-level configuration widget using the mapping created here. With this widget, editors can create a configuration page that allows visitors to choose the level of cookies they agree to.