Prerequisites for Episerver integration

To be able to use the Episerver integration, you'll need to have a few things set up first:

Features of the Episerver integration

Complying with user consent can be tricky on Episerver based sites due to cookies being set in multiple places. For this reason, the following features are part of the integration:

Cookie Consent Pop-up registration: ensure that the Cookie Information consent pop-up is shown on all necessary pages in the correct language.

IVistorConsentService (Implemented in VistorConsentService): you can query this service to find out whether the current visitor has given consent to a specific cookie category or cookie.

ICookieMappingService (Implemented in CookieMappingService): maps cookies to the correct categories for the IVisitorConsentService. You can access it via an IInitializeModule if you would like to add cookie definitions. By default, definitions are loaded from the configuration.

HtmlHelper.CreateConditionalCookieScript: this is an extension method that is found in the CookieInformation.Episerver.Helpers namespace. It can wrap a section of razor code and automatically load the snippet as soon as the user has given consent to cookies.

CookieConsentCriterion: this visitor group criterion allows editors to personalise content based on the user consents given.

HTTPModule: is a module that can clean server-side cookies that have been set (with no consent given) before returning a response. It can also remove cookies where consent has been withdrawn for them if a user updates their settings.

Episerver UI Integration: provides a shortcut to the Cookie Information dashboard from within the Episerver edit mode.

Installing the Episerver Integration

The Cookie Information Episerver extension can be found as a NuGet package. You can either download the package or install it via the command line using the following command (recommended):

Install-Package CookieInformation.Episerver -Version 1.0.16

Alternatively, there are also commands available for other package managers:

.NET CLI:

dotnet add package CookieInformation.Episerver --version 1.0.16

Package Reference:

<PackageReference Include="CookieInformation.Episerver" Version="1.0.16" />

Paket CLI:

paket add CookieInformation.Episerver --version 1.0.16

Configuring the Episerver Integration

The integration can be configured via the AppSettings (normally found in web.config).

The first things you'll be presented with are the cookie category mappings like so:

COOKIE:CONSENT:NECESSARY
COOKIE:CONSENT:FUNCTIONAL
COOKIE:CONSENT:MARKETING
COOKIE:CONSENT:STATISTIC
COOKIE:CONSENT:MISC

Each key should have a comma (",") separating cookie names. Instead of a cookie name, you can also use regular expressions - but the expression must start with "¨^" and end with "$".

Additional Settings

In addition to the normal configuration, there are some other settings you can tailor to your own liking:

COOKIE:REGISTER-CONSENT-SCRIPT

REGISTER-CONSENT-SCRIPT defaults to true. If you'd like to manually insert the pop-up script manually, then set it to false.

COOKIE:EMBED-DASHBOARD

EMBED-DASHBOARD defaults to false. This means that in Episerver edit mode, the menu integration will only link to the Cookie Information dashboard. If it is set to true, then it will be embedded in an iFrame.

COOKIE:FALLBACKCONSENT

FALLBACKCONSENT has a default value of false. If a cookie or category isn't known, then this indicates the default consent (in this case, that consent has not been given as is legally required).

COOKIE:REMOVEOLD

REMOVEOLD defaults to false. If it is set to true then cookies in a visitors browser that they have not given consent to will expire.

COOKIE:FILTER:DISABLE

FILTER:DISABLE defaults to false. If it is set to true, then the HTTPModule that automatically removes server side cookies from the response is disabled.

It can be useful to set the value to true for troubleshooting purposes as long as all server side cookies are already taken care of manually.

COOKIE:ALLOW-FOR-ROLES

ALLOW-FOR-ROLES has a default value of "Authenticated" and includes a comma-separated list of roles where all cookies should be allowed. The authentication check is disabled.

Allowing a script to fire immediately upon user acceptance of cookies

In order to set cookies as soon as consent is given, code should be wrapped in a JavaScript function - with the name of the function being provided to the cookie helper.

@if (VisitorConsentService.Current.ConsentsToCategory(CookieInformationCategories.MARKETING))
{
<script type="text/javascript">
// Script that will set a marketing cookie
console.log('There is consent to Marketing cookies');
</script>
}

If consent has already been given, then the function will run. If it hasn't, an eventhandler will register and the function will run as soon as the user has consented.

Setting custom cookies in server side code

In some cases, you might need to set custom cookies in your server side code. You can either access the VisitorConsentService via the static "Current" property or instead use Episerver's dependency injection (like in the example below):

[InitializableModule]
[ModuleDependency(typeof(EPiServer.Web.InitializationModule))]
public class CookieInit : IInitializableModule
{
public void Initialize(InitializationEngine context)
{
var cookieMapper = ServiceLocator.Current.GetInstance<ICookieMappingService>();
cookieMapper.RegisterCookieInCategory("MyServerSideCookie", CookieInformationCategories.FUNCTIONAL);
}

public void Uninitialize(InitializationEngine context)
{
}
}

Implementation Checklist

  1. A Cookie Information account with a domain added to the platform

  2. An up and running Episerver project

  3. Integration installed via NuGet or your package manager of choice

  4. Cookies mapped to categories

  5. Any further configuration changes you have made

Did this answer your question?