CookieInformation.Optimizely 2.1.0

CookieInformation Optimizely Content Cloud (EPiServer) Integration

Thank you for installing this integration between Cookie Information's Consent Management Platform(CMP) and Optimizely’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 Optimizely 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 Optimizely Profile Store tracking, ODP, 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 Optimizely 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 Optimizely’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.
• Taghelpers. Taghelpers to help you handle consents to cookies in your razor views. See below for more information.
• 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.
• HttpMiddleware 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.
• Optimizely UI integration. Providing a shortcut to your Cookie Information dashboard from within Optimizely’s edit mode.

Most of the above components can be enabled/disabled, controlled, and customized through configuration (appsettings.json) or through code during initialization (.AddCookieInformation()).

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 configuration (appsettings.json) or through code during initialization (.AddCookieInformation()). You should always begin by registrering the integration in your dependency injection. This typically happens in your Startup class. In the "ConfigureServices" method, add the following line below "AddMvc()":

services.AddCookieInformation(x => x.SetDefaults());

And if you want to use the response cleaning middleware, add the following line to configure method:

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    app.UseCookieInformationToCleanResponse();
}

All the configuration is done through the CookieConsentOptions class - and you have 2 options on how to set it:

1. You can set it in your appsettings file by adding this to the root node:

 "CookieInformation": {
   "RegisterConsentScript": true
 }

2. You can inject it in the configuration action that is a parameter when you call AddCookieInformation. For example:

services.AddCookieInformation(x => {x.SetDefaults();x.RegisterConsentScript = true;});

The options you can set are listed below. First are a set of lists where you can define which cookies should belong to the different categories. It is string lists, but the string can either be the cookie name, or a regular expression that should match the cookie name. Regular expressions must start with "^" and end with "$". For example: ^EPI-MAR-[a-z0-9-_]+$ will match any cookies named something like EPI-MAR-a3fa3252323. It is recommended to always call ".SetDefaults()" on the Options class to set the default cookies typically used by Optimizely CMS and common add-ons.

"Necessary"     String list of necessary cookies.
"Functional"    String list of functional cookies.
"Marketing"     String list of marketing cookies.
"Statistic"     String list of statistic cookies.
"Misc"          String list of miscellaneous cookies.

Next, we have the remaining configuration:

"RegisterConsentScript"         Bool. If true, the consent script will be registered on all pages. If false, you will have to register it yourself.
"UseGoogleConsentModeV2"        Bool. If true, the consent script will use Google's Consent Mode V2. Defaults to true.
"RegisterGoogleConsentModeV2"   Bool. If true, the consent script will register Google's Consent Mode V2 default settings (advanced). Defaults to true.
"GoogleConsentDefaults"         Object. The default consents for Google's Consent Mode V2. Only used if RegisterGoogleConsentModeV2 is true. Defaults to setting consents as 'denied'.
"ShowCookieInformationMenuItem" Bool. If true, a menu item will be added to the Optimizely UI, allowing you to easily navigate to the Cookie Information dashboard.
"EmbedDashboard"                Bool. Notice: Obsolete. This will always be treated as false and the dashboard will be opened in a new tab.
"FallbackConsent"               Bool. If true, the consent script will assume consent has been given, if the user has not given consent. This is useful for development and testing. Defaults to false.
"RemoveOld"                     Bool. If true, the consent script will remove cookies that the user has previously given consent to, but has now withdrawn consent to. Defaults to false.
"DisableFilter"                 Bool. If true, the consent script will not filter any cookies. This is useful for development and testing. Defaults to false.
"MimeTypesToFilter"             String List. A list of mime types that should be filtered. Defaults to "text/html".
"AllowForRoles"                 String List. A list of roles that automatically consents to all cookies. Defaults to "WebEditors" and "WebAdmins".
"WhitelistPath"                 String List. A list of paths that should not have cookies filtered.
"ShouldRegisterScriptForRequest"Delegate. A delegate that determines if it should add the Consent Script to pages. Useful if you want to disable the pop-up for certain visitors like performance monitors and screenshot software.

Usage examples: Checking consent

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))
{
    <script type="text/javascript">
        // Script that will set a marketing cookie
        console.log('There is consent to Marketing cookies');
    </script>
}

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"))
 {
     <script>
         //Code that sets a cookie called "MySpecialCookie" which is mapped to the proper categories.
          console.log('There is consent to MySpecialCookie');
     </script>
 }

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.

Usage Examples: Taghelpers

The integration also includes a set of taghelpers that can be used to help you handle consents to cookies in your razor views. The taghelper shown below will only render the content if the visitor has consented to the given category. It does not need a full page-refresh to render in case the consent changes. You can either specify consent categories directly, or you can specify a cookie name and the taghelper will lookup the category for you.

 <conditional-consent cookie-categories="MARKETING,STATISTIC" cookies="EPi:NumberOfVisits,cookie2">
     <on-consent>
         <iframe width="560" height="315" src="https://www.youtube.com/embed/[my-youtube-link]" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
     </on-consent>
     <not-consent>
         <div width="560" height="315">Nothing to see here!</div>
     </not-consent>
 </conditional-consent>

Usage Examples: HtmlHelpers

Razor code to register a script that will execute the included code the moment the proper consent has been given:

@using (Html.BeginConditionalConsent("Consent()", "NoConsent()", "EPi:NumberOfVisits", CookieInformationCategoryTypes.STATISTIC))
{
   <script>
       function Consent() {
           //Code that sets statistical cookies
           console.log('There is now consent for Statistical cookies');
       }
       function NoConsent() {
           console.log('There is not consent for Statistical cookies anymore');
       }
   </script>
}

A reference to the javascript method that should be invoked for concent given as well as when consent is not given, can parsed in as arguments to the BeginConditionalConsent method. It is possible to parse in both specific cookies as well as cookie catagories for the conditional consent. In the above example the Consent() will be invoked if the cookie EPi:NumberOfVisits OR the STATISTIC catagory has been given consent.

Usage Examples: Controller checking

Controller code to check if the visitor has consented to a certain cookie before adding code to set it:

 public class StartPageController : PageControllerBase<StartPage>
 {
     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 Optimizelys dependency injection as in this example.