Registering 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 interacting with a cookie consent web part), the system automatically clears all cookies that have a higher level from the visitor’s browser. You may also encounter problems with custom or third-party cookies not being stored if your site’s System -> Default cookie level setting has a lower value than Visitor, for example when managing tracking consent.

To register custom cookies, you need to add custom code to your project. Call the CookieHelper.RegisterCookie method (available in the CMS.Helpers namespace of the Kentico API), with the following parameters:

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

To ensure that your cookies are recognized correctly, call the RegisterCookie method at the beginning of the application’s life cycle – either during the initialization of a custom module class, or within suitable startup code if you are using the Kentico API in an external application.

Example

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

1. Open the Kentico web project in Visual Studio (using the WebSite.sln or WebApp.sln file).

2. Create a custom module class.

   • We recommend adding the class into a custom Class library project within the Kentico solution.

3. Override the module’s OnInit method and call the CookieHelper.RegisterCookie method.

   Copy

   
   
   
    using CMS;
   
    using CMS.DataEngine;
    using CMS.Helpers;
   
    // Registers the custom module into the system
    [assembly: RegisterModule(typeof(CustomInitializationModule))]
   
    public class CustomInitializationModule : Module
    {
        // Module class constructor, the system registers the module under the name "CustomInit"
        public CustomInitializationModule()
            : base("CustomInit")
        {
        }
   
        // Contains initialization code that is executed when the application starts
        protected override void OnInit()
        {
            base.OnInit();
   
            // Registers the "CustomCookie" with the 'Essential' cookie level
            // Ensures that the cookie is preserved for visitors who change their allowed cookie level below 'Visitor'
            CookieHelper.RegisterCookie("CustomCookie", CookieLevel.Essential);
        }
    }
   
   
    

The CustomCookie is now registered and can be used by visitors who allow only the Essential cookie level (either by interacting with a cookie consent web part or based on your site’s default cookie level).

// Saves a custom cookie named "CustomCookie" to the current visitor's browser,
// with "CustomValue" as its value and an expiration time of 1 year
CookieHelper.SetValue("CustomCookie", "CustomValue", DateTime.Now.AddYears(1));