Cookies

A cookie is a small piece of data that a website asks your browser to store on your computer or mobile device. The cookie allows the website to “remember” your past actions or preferences.

Xperience provides an extensible framework, built around cookie levels, for manipulating cookies – from assigning specific levels of allowed cookies to users and contacts, to registering custom cookies and their corresponding cookie levels.

Set the default cookie level

A website channel’s default cookie level determines which cookies the system stores in the browsers of visitors by default. To set the default cookie level:

1. Open Channel management application in Xperience.
2. Select a website channel.
3. Open the Channel settings tab.
4. In the Cookies section, choose a Default cookie level.
   • For an overview of individual cookie levels, see Cookie levels.
5. Select Save.

The system now uses the selected cookie level when evaluating which cookies should be stored.

Developers can add functionality to your website to allow visitors to give consent with tracking and increase their cookie level above the default. See Enable users to select a preferred cookie level.

Cookie levels

Xperience classifies cookies into several levels according to their purpose. These levels determine which cookies are set for administration users and website visitors. The following table lists the default levels available in the API (Kentico.Web.Mvc.CookieLevel class):

The numbers associated with each cookie level are integer constants, which allows you to further customize the granularity of available cookie levels. The levels ‘None’ and ‘All’ are set to an absolute value of 1000 to provide enough space for future Xperience updates or developer-specified custom levels.

Register custom cookies

If your website uses any custom or third-party cookies, we recommend that you register them with an appropriate cookie level. Unregistered cookies are processed with the Visitor level by default.

When a visitor adjusts their allowed cookie level (for example by accepting or revoking a consent), the system automatically clears all cookies of a level higher than consented from the visitor’s browser. You may also encounter problems with custom or third-party cookies not being stored if your website channel’s Default cookie level setting has a lower value than Visitor, for example when managing tracking consent.

Custom cookies are registered via the CookieLevelOptions object on application startup. The options object exposes a CookieConfigurations dictionary where you can add your cookies. Use the following parameters:

• key – the name of the cookie that you are registering.
• value – an integer value representing the cookie level required to use the cookie. You can access the default values in the Kentico.Web.Mvc.CookieLevel enumeration.

Example

The following example demonstrates how to register a custom cookie named CustomCookie with the Essential cookie level:

using Kentico.Web.Mvc;

var builder = WebApplication.CreateBuilder(args);

...

// Registers 'CustomCookie' with the 'Essential' cookie level in Xperience 
builder.Services.Configure<CookieLevelOptions>(options =>
{
    options.CookieConfigurations.Add("CustomCookie", CookieLevel.Essential);
});

The CustomCookie is now registered and can be used by visitors with the Essential and above cookie level (based on your website channel’s default cookie level, the users’ preferred cookie level, or other custom actions such as consent agreements). 

var cookieOptions = new CookieOptions
{
    IsEssential = true
};

// Adds the cookie to the response cookie collection
HttpContext.Response.Cookies.Append("cookieName", "cookieValue", cookieOptions);

Set and work with cookies

You can use the Xperience API to create and set custom cookies into a user’s browser. Use ICookieAccessor.Set within the scope of an HTTP request:

using Microsoft.AspNetCore.Http;

using Kentico.Web.Mvc;
...

// Contains an instance of 'ICookieAccessor' e.g., obtained using dependency injection
private readonly ICookieAccessor cookieAccessor;

cookieAccessor.Set("MyCookie", "SomeValue");

Cookies set without specifying any Microsoft.AspNetCore.Http.CookieOptions use the Lax SameSite mode by default. To set a different SameSite mode, configure the desired behavior via the options object. The Microsoft.ApeNetCore.Http.SameSiteMode enumeration stores all available values:

using Microsoft.AspNetCore.Http;

...

cookieAccessor.Set("CustomCookie", "CustomValue", new CookieOptions() { SameSite = SameSiteMode.Strict });

// Adds the Secure attribute to the cookie with 'SameSite=None'. 
// The user agent will include the cookie in an HTTP request only if the request is transmitted over a secure channel (typically HTTPS). 
cookieAccessor.Set("CustomCookie", "CustomValue", new CookieOptions() { 
                                                        SameSite = SameSiteMode.None,
                                                        Secure = true });

To get and remove cookies, use ICookieAccessor.Get and ICookieAccessor.Remove respectively.

// Gets the cookie called 'MyCookie' from the current request
cookieAccessor.Get("MyCookie");

// Removes the cookie called 'MyCookie' from the current request
cookieAccessor.Remove("MyCookie");

Enable users to select a preferred cookie level

In compliance with the cookie law, you can allow users to select their preferred cookie level. Use the SetCurrentCookieLevel method provided by the ICurrentCookieLevelProvider service.

The following code snippets demonstrate the usage of the ICurrentCookieLevelProvider API on a basic example. The code allows users to set their preferred cookie level via a simple form.

using Microsoft.AspNetCore.Mvc;
using Microsoft.AspNetCore.Mvc.Rendering;
using System.Collections.Generic;

using CMS.Helpers;

public class CookieLevelController : Controller
{
    private readonly ICurrentCookieLevelProvider cookieLevelService;

    // Initializes instances of required services using dependency injection
    public CookieLevelController(ICurrentCookieLevelProvider cookieLevelService)
    {
        this.cookieLevelService = cookieLevelService;
    }

    public ActionResult Index()
    {
        // Creates a list with the three default levels of cookie compliance relevant for visitors.
        // The CookieLevel class is used to directly extract integer values corresponding to each cookie level
        // so that no additional mapping is necessary.
        var cookieLevels = new List<object>() {
                new { label = "Essential", value = Kentico.Web.Mvc.CookieLevel.Essential.Level },
                new { label = "Visitor", value = Kentico.Web.Mvc.CookieLevel.Visitor.Level },
                new { label = "All", value = Kentico.Web.Mvc.CookieLevel.All.Level }
            };

        return View(new SelectList(cookieLevels, "value", "label"));
    }

    // Sets the cookie level for the current user
    // The value passed into the action from the corresponding view directly corresponds to one of the system's 
    // cookie levels thanks to the CookieLevel class.
    [HttpPost]
    [ValidateAntiForgeryToken]
    public ActionResult SetCookieLevel(int selectedValue)
    {
        // Sets the cookie level for the current user to the level corresponding to the provided value
        cookieLevelService.SetCurrentCookieLevel(selectedValue);

        return RedirectToAction(nameof(Index));
    }
}

The corresponding view contains a drop-down selector that allows users to select the desired level of cookies.

@model SelectList

@using (Html.BeginForm("SetCookieLevel", "CookieLevel", FormMethod.Post))
{
    @Html.AntiForgeryToken()
    @Html.DropDownListFor(x => x.SelectedValue, Model)
    <input type="submit" value="Select" />
}