Installing uSplit

  • by Ondrej Pialek
  • Monday, November 20, 2017

This is a step by step guide describing the installation process for uSplit, the Umbraco A/B testing plugin. uSplit officially supports Umbraco 7.4 and above, though it might be possible to install it on older sites as well. This guide also covers the Google API configuration in detail as Google API client credentials are required by the plugin.

Do you have uSplit installed? Read our user guide. Never heard of uSplit? Check the product page.

Installing uSplit

We are currently offering two parallel versions of uSplit – 1.0.x and 1.6.x. They contain the same functionaly but differ in the version of Umbraco they target: uSplit 1.0 is for Umbraco 7.5 and below and uSplit 1.6 is for Umbraco 7.6 and above.

NuGet is the preferred method of installation; it is much easier to distribute updates this way, and allows us to automate some of the setup as well. You must be running Umbraco 7.4 or later to be able to seamlessly install uSplit via NuGet, installing uSplit on an older Umbraco version will cause Umbraco to upgrade too. Check the note below for options to install uSplit on older sites.

Search for Endzone.uSplit using the NuGet Package Manager and select the appropriate version you want to install or simply run the following command from the Package Manager Console:

PM> Install-Package Endzone.uSplit

Once the package is installed, follow the instructions that appear on the screen – you will need to do a minor modification to your Web.config.

log4net dll dependency

This section is not relevenat for Umbraco 7.6 and above.

Umbraco 7.5 and below distribute a non-signed log4net library version 1.2.11 alongside its own DLLs, instead of having a dependency on the log4net NuGet package. When uSplit is added through NuGet, one of its dependencies adds a proper log4net dependency to the project. NuGet does not know about Umbraco’s log4net library, and will download another instance of it – it will however be a more recent version, and one that is strongly signed.

The newer log4net library overwrites the one from Umbraco, and your site will not start. Due to the signing mismatch a simple assembly binding redirect does not help. Instead, we need to provide both log4net libraries!

uSplit 1.0.x distributes Umbraco’s log4net dll as well and when installed places it into bin/log4net/1.2.11.0/log4net.dll. Simply modify your Web.config and add the lines bellow to make the unsigned old library available to Umbraco:

<dependentAssembly>
  <assemblyIdentity name="log4net" publicKeyToken="null" />
  <codeBase version="1.2.11.0" href="bin/log4net/1.2.11.0/log4net.dll" />
</dependentAssembly>
Installing on older sites (Umbraco 7.3): Older versions of Umbraco have a hard dependency on Newtonsoft.Json version 6. uSplit however requires newer version of Newtonsoft.Json due to its dependency chain (coming from the Google libraries). To install uSplit on an Umbraco 7.3 site use the manual installation.

Manual installation notes

uSplit may be installed manually through the backoffice as well. This is useful in cases where your projects do not use NuGet. Make sure you install the correct version of uSplit based on your version of Umbraco: 1.0 for Umbraco 7.5 and below, 1.6 for Umbraco 7.6 and above.

To install uSplit manually, you have two options:

  1. Installation through the Umbraco package repository
    • Open the Packages page on the Developers section
    • Search for uSplit and install the package
  2. Installation as a local package
    • Download uSplit from the Umbraco package repository
    • Open the Packages page on the Developers section
    • Install the downloaded zip file as a local package
upgrade your Newtonsoft.Json

This section is not relevenat for Umbraco 7.6 and above.

After the installation is over you may see an error. uSplit 1.0.x requires Newtonsoft.Json version 7 or above and you have to tell Umbraco to use that. v7 of the library is included in the uSplit package and was already copied to your bin folder during the installation process. Just add the following assembly redirect to your Web.config file and refresh the page:

<dependentAssembly>
  <assemblyIdentity name="Newtonsoft.Json" publicKeyToken="30ad4fe6b2a6aeed" culture="neutral" />
  <bindingRedirect oldVersion="0.0.0.0-7.0.0.0" newVersion="7.0.0.0" />
</dependentAssembly>

Obtaining Google API credentials

Google API credentials are used to authenticate the website when talking to Google. They do not grant access to any Google Analytics accounts, they merely identify the caller (the website). It is advisable to create new credentials per site or client, so that you manage the quota and access separately. There is a set of screenshots bellow this list to act as a visual guide should you need it.

  1. Register a project
  2. Enable the Analytics API for the project
  3. Customize the OAuth consent screen
  4. Generate OAuth Client ID credentials
    • Application type is “Web application”
    • Set Authorized JavaScript origins
      • don’t forget to list all your live, staging, and dev domains
      • (including e.g. http://localhost:PORT/ for local dev)
    • For the Authorized redirect URIs field you will need to enter absolute URLs for the above domains with the following path: /umbraco/backoffice/usplit/GoogleCallback/IndexAsync, e.g. http://your.domain.com/umbraco/backoffice/usplit/GoogleCallback/IndexAsync
  5. Client ID and secret are generated for you, take note of them.

Not sure where to click? Check the screenshots below:

uSplit setup

  1. Add the following AppSettings (all are required) to your web.config:
    • uSplit:googleClientId The Google API Client Id obtained as per above
    • uSplit:googleClientSecret The Google API Client Secret obtained as per above
    • uSplit:accountId The Id of the Google Analytics account you want to use
    • uSplit:webPropertyId The Id of the Google Analytics property you want to run experiments for
    • uSplit:profileId The Id of the Google Analytics profile where you want to store the experiments
    • Sample code looks like this:
      <add key="uSplit:googleClientId" value="771327635790-aj37cdgcrl7c33nei5rvih72cefitd4m.apps.googleusercontent.com" />
      <add key="uSplit:googleClientSecret" value="sbcFrLGMz6-U8--dF2RHI-1v" />
      <add key="uSplit:accountId" value="63366167" />
      <add key="uSplit:webPropertyId" value="UA-63366167-2" />
      <add key="uSplit:profileId" value="104332457" />
      
  2. Open the backoffice and navigate to the uSplit dashboard to verify the settings.
    • The dashboard is just under the Content tree, or simply go to /umbraco#/content/abtesting/dashboard/hello
  3. Click on the Re-authorize button to initiate the authentication flow.
    • If the API side if things is set up correctly, Google will present you with a consent screen you configured.
    • If you use multiple Google Accounts, Google will also ask you which account to authenticate with.
    • You will be redirected back to the backoffice.
    • Connected to Google API will indicate whether you successfully authenticated with the Google API.
    • Connected to Google Analytics Account will indicate whether the account you logged-in with has access to the actual Google Analytics account (set in AppSettings).
      • Note that the plugin will be usually set up by a developer, who might not have access to the Google Analytics Account. At this point the developer should hand over the plugin to the editors / managers of the site, who should have the necessary access; they should initiate the authentication flow themselves and log-in with an account that can access the desired Google Analytics property.
      • The authentication is only needed once and user credentials are not stored on the server. Only the token obtained from Google (which authorizes calls to the Analytics API) is stored.

If all went well your dashboard should look like this:

Reporting chosen variations to Google Analytics

uSplit handles all experiment decision making server side, it however needs to report the chosen variation to Google Analytics. It does so by embedding a small piece of JavaScript at the end of the HEAD tag when a page that contains an experiment is rendered. This small fragment hooks up into your existing GA code and does the necessary calls to report the chosen variations.

These days there are several ways to integrate GA into your pages and unless you are using the default – using analytics.jsscript in the HEAD tag – you might have to tell uSplit how to report the variations correctly. There are currently 3 extension methods that allow you to pick the best way (and place) to report experiment data to Google Analytics. If you are happy with the default behaviour you do not need to call these. If you need to customize the placement or the method of reporting, place one of these into your master layout, somewhere after you loaded your GA tracking code:

@Html.AbTesting.AnalyticsJsScriptTag() Renders a script tag with a series of analytics.jsJavaScript method calls that report any chosen variation to Google Analytics. This method should be called after you include your analytics.js script. Can report multiple experiments for a single page. If you do not include a call to any of these extension methods, this one will be rendered by default at the end of the HEAD tag.
@Html.AbTesting.CxApiScriptTags() Loads the Content Experiments script and renders another script tag that reports the chosen variation to Google Analytics using this API. Can be used with analytics.js, ga.js or GTM, but does not support reporting multiple experiments on a single page.
@Html.AbTesting.Custom(Func<IPublishedContentVariation[], string>) Gives you complete control over the way you report your variations to Google. It is up to you to render the correct JavaScript calls. Useful for instance if you use complext GTM logic and want to push these events over a named data layer.

 

Continue reading how to create and run your first experiment.

Need help with uSplit?

Send up
a flag