Recently, I added functionality to pages which contain the Control Script (these are usually test pages). This new functionality allows you to obtain more information about the variations and combination chosen for the visitor to a experiment, allowing you more flexibility in developing customized tests. I will elaborate on testing techniques which use these features in other articles. In this article, I want to simply document the new functionality in detail.
The utmx function
All the new functionality are accessed via the utmx function which is defined as a consequence of including the Control Script on a page. The utmx function is designed to be the single entry point for most current and all future functionality provided to test pages. Its signature is:
utmx( feature, arg1, arg2, ... argn )
The first argument is a string which describes the desired feature requested. The second, third, etc, arguments are dependent on the requested feature.
The value that the utmx function returns is dependent on the requested functionality. It may be a string, a number or other value. However, no matter what feature is requested, the utmx function may return undefined. The undefined return value may indicate that the utmx function was not redefined by the Control Script, and that any GWO related functionality on the page should show default (original) content or take default behavior. To illustrate this point, consider what the beginning of the Control Script looks like:
<script>
function utmx_section(){}function utmx(){}
(function(){var k='3923492669',d=document,l=d.location,c=d.cookie;function f(n){
.....
Notice that the utmx function is initially defined to have an empty body. When a function like this is called in JavaScript, the return value will be undefined. If, for whatever reason, the Control Script is unable to load siteopt.js, which redefines the utmx function, this original definition will remain and return undefined for anyone who calls it. In order to have pages not break under these circumstances, it is important to check the return from utmx for undefined and take the appropriate actions.
Variation Information
The following two features allow you to obtain information about what variation was chosen for a given section:
utmx( "variation_number", section_name )
and,
utmx( "variation_content", section_name )
In each case, the section name is the name (a string) of the section for which you want the information. This is the same value you would pass to the utmx_section function for a multi-variate experiment. In the case of an A/B experiment, GWO creates a single section called “A/B” which can be used here as well.
The “variation_number” feature returns either undefined or an integer number between 0 and N-1 where N is the number of variations defined for the given section, including the original. If 0 or undefined is returned, this indicates that the original content or behavior for the given section was chosen for this visitor. Values 1 through N-1 indicate that a non-original alternative for the given section was chosen for this visitor. In this case, the appropriate alternative action should take place.
The “variation_content” feature returns either undefined or a string. If undefined is returned, this indicates that the original content or behavior for the given section was chosen for this visitor. Otherwise, a string is returned, indicating that a non-original alternative for the given section was chosen for this visitor. The value of this string is exactly what was entered in the GWO user interface as the value of the variation chosen for the visitor. In the case of an A/B experiment, the value returned is the alternative URL entered in GWO user interface, exactly as it was entered.
Both of these features can indicate non-original alternatives for the given section for both “preview” and “live” page requests and should be used to alter the visuals or behavior of the page. A “live” request is a test page viewed by a visitor while the test is running, as opposed to a “preview” request which is one performed by the GWO preview window.
Combination Information
The following two features allow you to obtain information about what combination was chosen for a “live” visitor. Note that under “preview” requests, no combination information is available, undefined will be returned. These features apply only to “live” requests. Because of this, these features should not be used for altering the appearance or behavior of a test page. They can only be used to indicate what combination was chosen for a visitor to a running experiment.
utmx( "combination" )
and,
utmx( "combination_string" )
The “combination” feature returns either undefined or an integer between 0 and M-1 where M is the total number of combinations defined for the experiment, including the original. If undefined is returned, this indicates that this test page request was not a live request. If 0 is returned, this indicates that the original combination was chosen for the visitor. Otherwise, 1 through M-1 indicate that a non-original alternative was chosen for the visitor. Note that M is the product of the variation sizes of all the sections defined for the experiment. So, if you have an experiment with two sections, say, headline and image, and the headline has 3 alternatives and the image has 4 alternatives (each including the original), then M will be 12.
The “combination_string” feature has similar semantics as the “combination” feature. It returns undefined under the same conditions. However, the return value is a string with the variation numbers for each section separated by dashes. For example a 3 section multi-variate experiment may return “3-0-2” where 3 is the variation number for the first section, 0 for the second and 2 for the third. In this example, “0-0-0” would indicate that the original combination was chosen for the visitor. Again, undefined indicates that this was not a “live” request.
For A/B experiments, the combination features behave like a multivariate experiment where there is only one variable.
An example of using the combination information can be found in this article: Poor Man’s GWO/Analytics Integration.
Declaring Multivariate Sections
When using the above functionality for implementing tests, you will probably no longer use the standard multi-variate section script. For example:
<script>utmx_section("Button")<script>
<input type=button" value="Click Me">
</noscript>
The standard section script does two things. First, it declares the section named by the argument to the utmx_section function (Button, in this case). Secondly, it implements the actual replacement of the default content should a visitor been chosen to see an alternative variation.
When implementing the more advanced techniques for experiments, you may frequently no longer use the utmx_section function. However, you will still need to declare a section so that GWO will know the schema of your experiment. To declare a section without impacting your test page, you can use a special HTML comment. For example:
<!-- utmx section name="Section1" -->
<!-- utmx section name="Section2" -->
Declares two sections, but otherwise, has no impact on the page in which it is present (because they are comments). This way, when you validate your test page in the GWO UI, GWO will see the two sections you intend to declare. Then, the implementation of those sections on your page is under your, separate, control.
After creating a GWO experiment, how do I go back and view the tracking, conversion and control script code again? I can’t find a way to access that 🙁
anon : August 17, 2009 9:54 PMYes, the GWO user interface lacks this ability. However, if you go to the reports page for your running experiment, and change “exptreports” in the URL to “installcode” (for MVT experiments) or “ab_installation_instructions” (for A/B experiments), you should get to see the install instructions.
Eric Vasilik : August 20, 2009 6:24 PMThanks for that tip. It will come in handy the next time I need to set up GWO for a new client who has already tried it out.
anon : August 20, 2009 8:14 PMI’m seeing like 8% of traffic returning combination as undefined, all visitors using IE (6,7,8). Is this “normal” behaviour; is it related to IE javascript engine not overwritting utmx() function properly or because siteopt.js is not loaded properly? Have you encountered similar issues before? Thanks
Andrei Gherasim : November 9, 2009 1:54 AMAndrei,
Undefined may indicate the original under some circumstances, or indicate a failure of the control script of some kind.
– Eric
Eric Vasilik : December 27, 2009 8:08 PM