Logging custom A/B testing conversions

Conversions represent actions performed by the site’s visitors, and are used to evaluate different variants of pages during A/B testing.

The system provides a default set of conversions for the most common types of visitor actions, but developers can also extend the A/B testing conversion functionality. See the following customization scenarios:

• Registering custom conversion types
• Logging conversions in custom code

Registering custom conversion types

Use the following approach to register custom conversion types for A/B testing:

1. Open the solution of your Xperience administration project in Visual Studio (using the WebApp.sln file).

2. Add a custom module class and override the module’s OnInit method:

3. For each conversion type, prepare an object of the ABTestConversionDefinition class. The constructor accepts the following string parameters:

   • Name – a unique identifier of the conversion type. Used in the API when logging conversions.

     Tip: If you have multiple custom conversion types, create a separate class with constants storing the names (identifiers). You can then share the code between your administration and MVC applications, and use the constants when logging the conversions.

   • Display name – the name shown to marketers in the administration interface when defining conversions for A/B tests. Can be localized by setting the value to an expression in format {key}. Replace “key” with the key of a resource string.

4. Call the ABTestConversionDefinitionRegister.Instance.Register method with the ABTestConversionDefinition object as a parameter.

   Basic example

   Copy

   
   
   
    using CMS;
    using CMS.DataEngine;
   
    using CMS.OnlineMarketing;
   
    // Registers the custom module into the system
    [assembly: RegisterModule(typeof(CustomABTestingModule))]
   
    public class CustomABTestingModule : Module
    {
        // Module class constructor, the system registers the module under the name "CustomABTesting"
        public CustomABTestingModule()
            : base("CustomABTesting")
        {
        }
   
        // Contains initialization code that is executed when the application starts
        protected override void OnInit()
        {
            base.OnInit();
   
            // Defines a custom conversion type
            var conversionTypeDefinition = new ABTestConversionDefinition("CustomConversion", "Custom conversion");
   
            // Registers the custom conversion type
            ABTestConversionDefinitionRegister.Instance.Register(conversionTypeDefinition);
        }
    }
   
   
    

5. Rebuild the solution.

Marketers can now select the registered conversion types when configuring tests in the A/B tests application of the administration interface. Custom conversion types appear among the default types (the overall list is sorted in alphabetical order according to the display names).

Custom conversion types are not logged automatically. Developers need to adjust the code of the MVC live site application, and log the conversions in the appropriate location using the API. See Logging conversions in custom code.

Defining configurable conversion types

Some types of conversions require additional input, such as an identifier of a related object or other type of condition. For example, marketers need to select a specific newsletter when adding the default Newsletter subscription conversion type to an A/B test. The system then only logs the conversion when a visitor subscribes to the selected newsletter (not any newsletter in general).

The user interface of the configuration input is provided by a form control, which is specified in the registration code of the conversion type.

Developers can leverage this type of configuration for custom conversion types:

1. Edit the code where the conversion type’s ABTestConversionDefinition object is defined.
2. Specify the form control used for the configuration input – prepare an object of the ABTestFormControlDefinition class. The constructor accepts the following parameters:
   • Form control – identifies the form control. Two options are available:
     • a string matching the Code name of the form control (you can find the code names on the Form controls tab of the Administration interface application within the Xperience administration interface)
       – or –
     • the System.Type of the form control class (i.e. a class inheriting from FormEngineUserControl)
   • Input caption – the text of the label displayed before the input to marketers in the A/B test configuration interface. Can be localized by setting the value to an expression in format {key}. Replace “key” with the key of a resource string.
   • (Optional) Form control parameters – an IDictionary collection that can be used to set the form control’s parameters. Each key must match the name of a parameter and have a value of the appropriate type.
3. Add the ABTestFormControlDefinition object as another parameter of the conversion type’s ABTestConversionDefinition constructor.
4. Rebuild the solution.

For example, the following code registers a custom conversion type with a “Day of the week” selector based on the system’s Drop-down list form control:

using System;
using System.Collections.Generic;

using CMS.OnlineMarketing;

...

// Contains initialization code that is executed when the application starts
protected override void OnInit()
{
    base.OnInit(); 

    // Prepares option parameters for a Drop-down list form control (days of the work week)
    var options = new List<string> {
        DayOfWeek.Monday.ToString(),
        DayOfWeek.Tuesday.ToString(),
        DayOfWeek.Wednesday.ToString(),
        DayOfWeek.Thursday.ToString(),
        DayOfWeek.Friday.ToString() 
    }; 

    // Prepares a definition for a 'Drop-down list' form control containing the specified options
    var formControlDefinition = new ABTestFormControlDefinition(
        "DropDownListControl",
        "Day of the week",
        new Dictionary<string, object> { { "options", String.Join(Environment.NewLine, options) } }
    );

    // Defines a custom conversion type with an input field that allows users to select a day of the week
    var advancedConversionTypeDefinition = new ABTestConversionDefinition("AdvancedConversion", "Advanced conversion", formControlDefinition);

    // Registers the custom conversion type
    ABTestConversionDefinitionRegister.Instance.Register(advancedConversionTypeDefinition);
}

When marketers add this advanced custom conversion type to a test in the A/B tests application, they can select a day of the work week.

The selected day limits when conversions of this type are logged. Developers need to ensure that the condition is reflected in the code used to log the custom conversions (by supplying an Item identifier value matching the name of the current day). For more information, see Logging conversions in custom code.

Logging conversions in custom code

The Xperience API allows developers to extend the A/B testing functionality by logging conversions in any location within the website’s code. Custom logging is possible for both custom registered conversion types and the system’s default types.

1. Open the solution of your MVC live site project in Visual Studio.

2. Identify the part of your site’s code where you wish to log the conversion (for example in a controller action that displays a specific page or handles a related event).

3. Get an instance of the IABTestConversionLogger service (available in the CMS.OnlineMarketing namespace) and call the LogConversion method. Specify the following required parameters:

   • Conversion name – the name (unique identifier) of the conversion type that you wish to log. The names of the default conversion types are available as constants within the ABTestConversionNames class (found in the CMS.OnlineMarketing namespace).
   • Site name – the code name of the current site.

4. When logging conversion types that have a configuration input, you also need to set a third parameter for the LogConversion method:

   • Item identifier – an identifier (string) of the object related to the logged conversion, or another conditional value based on the context in which the conversion is being logged.

     The conversion is only logged if the supplied Item identifier matches the value saved by the configuration input’s form control for the given A/B test. For example, the default Newsletter subscription conversion type requires marketers to select a specific newsletter, which saves the given newsletter’s code name into the configuration of the given A/B test. When a newsletter subscription occurs, the given newsletter’s code name is supplied as the item identifier, so conversions are only logged if there is a match with the configuration of the related A/B test.

   LogConversion optional parameters

   Additionally, the following optional parameters are available for the LogConversion method:

   • Default value – decimal that sets the default value logged for the conversion. Only used if a different Value is not specified in the conversion settings for the given A/B test.
   • Count – integer that sets the number of logged conversion hits.
   • Culture – the culture code with which the conversion is logged (i.e. the website language version selected by the visitor performing the conversion). If not specified, the application’s current thread culture is used.

5. Rebuild the solution.

using System;

using CMS.Base;
using CMS.OnlineMarketing;

...

// Instance of the A/B test conversion logging service
private readonly IABTestConversionLogger abTestConversionLogger;
// Instance of a service used to get the name of the current site
private readonly ISiteService siteService;

// Example of a controller constructor that initializes service instances using dependency injection
public PageController(IABTestConversionLogger abTestConversionLogger, ISiteService siteService)
{
    this.abTestConversionLogger = abTestConversionLogger;
    this.siteService= siteService;
}

...

// Logs a hit for the default user registration conversion type
abTestConversionLogger.LogConversion(ABTestConversionNames.USER_REGISTRATION, siteService.CurrentSite.SiteName);

// Logs a hit for a custom conversion type with the 'CustomConversion' name
abTestConversionLogger.LogConversion("CustomConversion", siteService.CurrentSite.SiteName);

// Logs a hit for a custom conversion type with the 'AdvancedConversion' name
// Supplies the name of the current day of the week as the item identifier, 
// which ensures that the conversion is only logged if there is a match with the selected day in the A/B test configuration
abTestConversionLogger.LogConversion("AdvancedConversion", siteService.CurrentSite.SiteName, DateTime.Now.ToString("dddd"));