JavaScript API reference

Before diving into the JavaScript API make sure you’ve signed-up and installed Musketeer.

Musketeer(‘test’, testName, variants, [options], [callback])

Description

Creates an A/B test and participates the user to the test. The user is automatically assigned to one of the variants depending on the type of the test. See Test types for more information on the different types of tests.

When a user participates a test for the first time, the participate event is emitted with the test’s name and variant’s name as arguments.

See Musketeer(‘convert’, testName) on how to convert a user in a test.

Argument Description
testName The name of the test. The name should be between 1 and 32 characters and may only contain the characters a-z, A-Z, 0-9, - and _.
variants

An array of variants or variant names.

In a test, at least two variants should exist and the variant names may only contain the characters a-z, A-Z, 0-9, - and _. If no variants are specified, two default variants are created: variant named A, and another variant named B. If the type of the test is random you can also specify a weight per variant. If you do not specify a weight, all variants will receive an equal weight.

To provide a weight per variant:

[{
        name: 'A',
        weight: 0.75,
}, {
        name: 'B',
        weight: 0.25,
}]

And to create two variants with an equal weight:

['A', 'B']
[options]

An optional options object for the test.

Key Description
type The type of test to create: random, bandit.
[callback] The callback function which is invoked with the variantName and testName as arguments.

Example

1
2
3
4
5
6
7
8
9
// Creates test `MyFirstTest` with variants A and B with no options.
Musketeer('test', 'MyFirstTest', ['A', 'B'], { type: 'bandit' }, function (variantName) {
        if (variant === 'A') {
                // This is A.
        }
        else if (variant === 'B') {
                // And B.
        }
});

Musketeer(‘convert’, testName)

Description

Converts a user for the given test. Before converting a user make sure they’re participating the test, see Musketeer(‘test’, testName, variants, [options], [callback]).

After a user reaches the conversion goal, call this method to convert the user in the test.

When a user converts in a test, the convert event is emitted with the test’s name and variant’s name as arguments.

Argument Description
testName The name of the test in which the user converted.

Example

1
2
// Convert the user for `MyFirstTest`.
Musketeer('convert', 'MyFirstTest');

Musketeer(‘on’, eventName, listener)

Description

Adds the listener function to the listeners for the event named eventName. To remove a listener, use Musketeer(‘off’, eventName, [listener]).

Argument Description
eventName

The name of the event.

The following events are available.

Event Description
load This event is emitted after the Musketeer library finished loading.
participate This event is emitted when a user participates a test. listener is invoked with testName and variantName. See Musketeer(‘test’, testName, variants, [options], [callback]).
convert This event is emitted when a user converts in a test. listener is invoked with testName and variantName. See Musketeer(‘convert’, testName).
listener The callback function.

Example

1
2
3
Musketeer('on', 'participate', function (testName, variantName) {
        //
});

Musketeer(‘off’, eventName, [listener])

Description

Removes the listener function or all listeners from the event eventName.

Argument Description
eventName The name of the event.
[listener] The listener function to remove. If not specified, all listener functions will be removed.

Example

1
Musketeer('off', 'participate');

Musketeer(‘config’, config)

Description

Sets the config values of Musketeer.

Argument Description
config

The config to set.

Config Description
defaultTestType The default test type to use when no type has been specified. The default is random.
participateTimeout The participate timeout in miliseconds. The default is 1000 ms. If participating a test fails within this time, Musketeer will fallback to the random test type which doesn’t require a network connection.

Example

1
2
3
4
Musketeer('config', {
        defaultTestType: 'random',
        participateTimeout: 1000,
});

Musketeer(‘identify’, userID)

Description

Sets the user’s unique identifier, for example, your user’s id from your datastore. It’s recommended that you call identify once the user signs into your app or website.

Using identify helps Musketeer to serve the same variant to the same user on different devices or browsers.

Argument Description
userID The unique user id of the user, either a string or a number.

Example

1
Musketeer('identify', user.id);

Musketeer(‘set’, properties)

Description

Sets specific properties to the current user.

These properties can be used in filtering and analysing. For example, you can set the user’s gender so you can analyse the behaviour of your tests per gender.

Argument Description
properties A key-value object of user properties.

Example

1
2
3
4
Musketeer('set', {
        gender: 'Male',
        age: 18,
});

Musketeer(‘check’)

Description

Checks the current DOM for HTML-based tests. By default, check is triggered automatically. Only use this method if you know what you are doing.

In HTML- and CSS-based tests, Musketeer needs to check the DOM for attributes which require actions. Musketeer checks changes at various moments, like location changes, but sometimes it’s required to manually let Musketeer know to re-check the DOM, like when your client-side controllers finished loading or your components finished rendering.

See HTML-based tests for more information on HTML-based tests.

Example

1
Musketeer('check');