CookieInformation.Episerver

==== CookieInformation Episerver Integration ====

Thank you for installing this integration between Cookie Information's Consent Management Platform(CMP) and Episerver’s Content Management Platform. The integration consists of a set of tools that help you to easily comply with the current regulations, by collecting and documenting valid consents from your visitor, in accordance with GDPR and ePrivacy. In the following instructions, you'll learn exactly which tools and functionalities are included and how you start using them.

== Background == The EU’s privacy legislations, GDPR and ePrivacy, provide all European website owners with a complex set of challenges and tasks that they need to fulfill to stay compliant.

You can quickly start collecting valid consents on your website. With a few steps, you have access to the tools you need to become compliant on your website. The platform makes editing & customizing your Consent Solution very easy. -Simple set up -Manage scanning depth & frequency -Block cookies until your users have given their consents -Unlimited test domains -Create custom popups or choose between multiple templates -Improvement of opt-in rates -40+ languages for multilingual websites -Features shared-consent for multibrand organizations

Besides all the functionalities that are native to the Cookie Information Platform, this integration also allows you to easily control cookies set in different places in Episerver, which otherwise would be a time-consuming task, this includes:

-Cookies set by server-side Episerver functionality, addons, and your own server-side code, like Visitor Groups, A/B Testing, e-commerce, etc..
-Cookies set by javascript (either your own, or 3rd party) referenced in the site views and javascript. For example Episerver Profile Store tracking, Google Analytics, and so on.
-Cookies set by embedded elements in site views, or in content added by editors. For example youtube videos, Disqus comments, LinkedIn profiles, or ShareThis social media sharing.
-Cookies set in views or embedded elements, this package provides a set of helper methods to easily allow developers to wrap that code in an IF statement, only using it if consent has been given. 
-Cookies in embedded html inserted by editors (like youtube videos added to an XHTML field), this package provides a Visitor Group criteria, so the built-in personalization functionality in Episerver can be used to either show the video, or an alternative that does not set cookies. 
-Cookies set server-side, this package includes an HTTP Module that attaches to the end of the server cycle, in order to automatically 'wash' any cookies the current visitor has not given consent to from the response. It can even expire old cookies the visitor has which no longer has consented. 
-On top of that, this integration also injects the Cookie Consent banner and adjusted to the selected language, and provides a shortcut to the Cookie Information Dashboard from within Episerver’s Edit mode.
-Tagmanagers is supported but has to be handled separately, please refer to support.cookieinformation.com

== Overview == The following tools and components are included:

-Cookie consent pop-up registration. By default, this will automatically ensure that the Cookie Informations consent pop-up is shown on all pages, in the proper language.
-IVisitorConsentService (Implemented in VisitorConsentService). Query this service (it is a singleton that can also be accessed as VisitorConsentService.Current) at any time to find out if the current visitor has given consent to a specific cookie category - or a specific cookie.
-ICookieMappingService (Implemented in CookieMappingService). The service is responsible for mapping cookie-names to categories for the IVisitorConsentService. You can access this in an IInitializeModule if you want to programmatically add cookie definitions. By default, definitions will be loaded from the configuration.
-HtmlHelper.CreateConditionalCookieScript. An extension method found in CookieInformation.Episerver.Helpers namespace, which can wrap a section of razor code, and automatically load it as soon as cookie consent has been provided.
-CookieConsentCriterion. A Visitor group criteria that allows editors to personalize content based on the consents given.
-HTTPModule that automatically can 'wash' server-side cookies set without consent before returning the response. It can even remove formerly set cookies where consent has been withdrawn.
-Episerver UI integration. Providing a shortcut to your Cookie Information dashboard from within Episerver’s edit mode.

Most of the above components can be enabled/disabled, controlled, and customized through configuration (AppSettings). Typically they can be found in the web.config.

== Installation and Configuration == First of all, you need to create an account with Cookie Information - if you don't already have one. You can get started with a free trial account which can be created here: https://cookieinformation.com/registration. When you have created your account, you need to configure both your public domain as well as any internal test/development domains in the Cookie Information Platform. If the domains are not configured, the consent pop-up will not show on your site.

The integration itself is installed using Nuget - and then you can configure it through AppSettings, typically found in web.config. Note that if you have a separate AppSettings configuration file, you'll need to manually move the AppSettings installed by the nuget to that file.

The first part is Cookie/Category mappings: COOKIE:CONSENT:NECESSARY COOKIE:CONSENT:FUNCTIONAL COOKIE:CONSENT:MARKETING COOKIE:CONSENT:STATISTIC COOKIE:CONSENT:MISC Each of those keys should have a comma (",") separated list of cookie names. In the place of a cookie name you can also put a Regular Expression - but it must start with "^" and end with "$". For example: ^EPI-MAR-[a-z0-9-_]+$ will match any cookies named something like EPI-MAR-a3fa3252323.

There are these additional settings to control the overall operation of the integration:

COOKIE:REGISTER-CONSENT-SCRIPT
    Defaults to TRUE. Set it to false, if you want to manually insert the Consent box script.

COOKIE:EMBED-DASHBOARD
    Defaults to FALSE, which means that in the Episerver Edit mode menu the integration will purely link to the Cookie Information dashboard. If set to true, then it will be embedded in an iFrame.

COOKIE:FALLBACKCONSENT
    Defaults to FALSE. If a cookie or a category is unknown - this indicates the default consent assumed.

COOKIE:REMOVEOLD
    Defaults to FALSE. If set to true, will expire cookies in the visitors browser that they have not given consent to.

COOKIE:FILTER:DISABLE
    Defaults to FALSE. If set to true, disables the HTTPModule that automatically removes server side cookies from the response. Can be set to true for troubleshooting or slight performance enhancements, assuming all server side cookies are already handled manually.

COOKIE:ALLOW-FOR-ROLES
    Defaults to "Authenticated". A comma separated list of roles where all cookies should be allowed, and the check disabled.

== Usage examples ==

Razor view checking if the visitor has consented to a given category before adding javascript that will include it: @if (VisitorConsentService.Current.ConsentsToCategory(CookieInformationCategories.MARKETING)) { } The code in question will only be shown if the specific consent requested has been given at the time of server-side execution.

Razor view checking if the visitor has consented to a named cookie (which should be mapped to categories): @if (VisitorConsentService.Current.ConsentsToCookie("MySpecialCookie")) { } In this case we first lookup the cookie by name in our mappings (typically defined in configuration) and then check if a consent has been given to that category it belongs to.

Razor code to register a script that will execute the included code the moment the proper consent has been given: @using (Html.CreateConditionalCookieScript(CookieInformationCategories.STATISTIC, "MyInit()")) { } In this case, we want to set the cookies as soon as the consent is given - not after the next server roundtrip. In order to do this, we should wrap our code in a javascript function and provide the name of that function to the cookie helper. If consent is already provided, the function will simply be run. If not, an eventhandler will be registrered and the function will be run as soon as the client has consented. This works well with for example Google Analytics tracking.

Controller code to check if the visitor has consented to a certain cookie before adding code to set it: public class StartPageController : PageControllerBase { private readonly IVisitorConsentService visitorConsentService; public StartPageController(IVisitorConsentService consentService) { this.visitorConsentService = consentService; }

    public ActionResult Index(StartPage currentPage)
    {
        var model = PageViewModel.Create(currentPage);

        //Set cookie
        if (visitorConsentService.ConsentsToCategory(CookieInformationCategories.FUNCTIONAL))
        {
            Response.Cookies.Add(new System.Web.HttpCookie("MyServerSideCookie", "Cookie Value"));
        }


        return View(model);
    }
}

Sometimes you need to set certain custom cookies in your own serverside code. In those cases you can of course use the same methods to test for validity. You can either access the VisitorConsentService through the static 'Current' property, or use Episervers dependency injection as in this example.

Initialization code to register cookie/category mappings by code (as opposed to by configuration): [InitializableModule] [ModuleDependency(typeof(EPiServer.Web.InitializationModule))] public class CookieInit : IInitializableModule { public void Initialize(InitializationEngine context) { var cookieMapper = ServiceLocator.Current.GetInstance(); cookieMapper.RegisterCookieInCategory("MyServerSideCookie", CookieInformationCategories.FUNCTIONAL); }

    public void Uninitialize(InitializationEngine context)
    {
    }
}

This is an alternate approach to simply adding the cookiename to the AppSettings. This could for instance work well if you are developing and add-on for Episerver and don't want to modify the appsettings, but rather simply add support for your own cookies.