Prerequisites for Optimizely integration
To be able to use the Optimizely integration, you'll need to have a few things set up first:
An account with Cookie Information. If you haven't created one yet, please visit go.cookieinformation.com and sign up.
The domain must be in the Cookie Information Platform.
A Visual Studio project with Optimizely (version 12 or lower) set up and running. If you have yet to do this, please refer to the Optimizely documentation for setting up a project.
Features of the Optimizely integration
Complying with user consent can be tricky on Optimizely-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.
Optimizely UI Integration: provides a shortcut to the Cookie Information dashboard from within the Optimizely edit mode.
Installing the Optimizely Integration
The Cookie Information Optimizely extension can be found as a NuGet package. Version 2.0.1 is still in the pre-release stage, please enable these so you are able to find it.
You can either download the package or install it via the command line using the following command (recommended):
Install-Package CookieInformation.Episerver -Version 2.0.1
Alternatively, there are also commands available for other package managers:
.NET CLI:
dotnet add package CookieInformation.Episerver --version 2.0.1
Package Reference:
<PackageReference Include="CookieInformation.Episerver" Version="2.0.1" />
Paket CLI:
paket add CookieInformation.Episerver --version 2.0.1
Configuring the Optimizely 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 Optimizely 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, the 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 Optimizely'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
A Cookie Information account with a domain added to the platform
An up-and-running Optimizely project
Integration installed via NuGet or your package manager of choice
Cookies mapped to categories
Any further configuration changes you have made
Related articles: