API client / Methods / A/B Test

Jun. 08, 2023

Add A/B test

Required API Key: any key with the setSettings ACL

Method signature

$analytics->addABTest(array abTest)

analytics.add_ab_test(Hash abTest)

analytics.addABTest(object abTest)

analytics.add_ab_test(dict abTest)

analyticsClient.addABTest(
  _ abTest: ABTest,
  requestOptions: RequestOptions? = nil,
  completion: Result<WaitableWrapper<ABTestCreation>> -> Void
)

suspend fun ClientAnalytics.addABTest(
    abTest: ABTest,
    requestOptions: RequestOptions? = null
): CreationABTest

analytics.AddABTest(ABTest abTest)

analytics.addABTest(ABTest abTest)

client.AddABTest(ABTest abTest)

add abTest abTest

See code examples

We released a new version of the PHP API client in public beta. Read the beta documentation for more information.

We released a new version of the JavaScript API client in public beta. Read the beta documentation for more information.

We released a new version of the Java API client in public beta. Read the beta documentation for more information.

You’re currently reading the JavaScript API client v4 documentation. Check the migration guide to learn how to upgrade from v3 to v4. You can still access the v3 documentation.

You’re currently reading the Ruby API client v2 documentation. Check the migration guide to learn how to upgrade from v1 to v2. You can still access the v1 documentation.

About this method

Create an A/B test.

You can set an A/B test on two different indices with different settings, or on the same index with different search parameters by providing a customSearchParameters setting on one of the variants.

Examples

Read the Algolia CLI documentation for more information.

Add an A/B test

Copy

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
$endDate = new \DateTime('tomorrow');
$endDate = $endDate->format('Y-m-d\TH:i:s\Z');


$analytics = AnalyticsClient::create(
  'YourApplicationID',
  'YourWriteAPIKey'
);

$analytics->addABTest([
  'name' => 'myABTest',
  'variants' => [
    [
      'index' => 'indexName1',
      'trafficPercentage' => 90,
      'description' =>  'a description'
    ],
    [
      'index' => 'indexName1-alt',
      'trafficPercentage' => 10
    ],
  ],
  "endAt" => $endDate,
]);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
tomorrow = Time.now + 24*60*60

abtest = {
  name: 'myABTest',
  variants: [
    {
      index: 'indexName1',
      trafficPercentage: 90,
      description: 'a description'
    },
    {
      index: 'indexName1-alt',
      trafficPercentage: 10
    },
  ],
  endAt: tomorrow.strftime("%Y-%m-%dT%H:%M:%SZ"),
}

analytics = Algolia::Analytics::Client.create('YourApplicationID', 'YourWriteAPIKey')
analytics.add_ab_test(abtest)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
const endAt = new Date();
endAt.setDate(endAt.getDate() + 1);

const abTest = {
  name: 'myABTest',
  variants: [
    {
      index: 'indexName1',
      trafficPercentage: 90
    },
    {
      index: 'indexName1-alt',
      trafficPercentage: 10,
      description: 'a description'
    },
  ],
  endAt: endAt.toISOString().replace(/\.[0-9]{3}/, '')
}

const analytics = client.initAnalytics({
  // optional parameters
  region: 'de',
  appId: 'YourApplicationID',
  apiKey: 'YourWriteAPIKey',
});
analytics.addABTest(abTest).then(({ abTestID }) => {
  console.log(abTestID);
});

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
ab_test = {
    'name': 'myABTest',
    'variants': [
        {
            'index': 'indexName1',
            'trafficPercentage': 90,
            'description': 'a description'
        },
        {
            'index': 'indexName1-alt',
            'trafficPercentage': 10
        },
    ],
    'endAt': datetime.datetime.utcnow().replace(day=29).strftime(
        "%Y-%m-%dT%H:%M:%SZ"),
}

analytics = AnalyticsClient.create(
    'YourApplicationID',
    'YourWriteAPIKey'
)

analytics.add_ab_test(ab_test)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
let analyticsClient = AnalyticsClient(appID: "YourApplicationID", apiKey: "YourWriteAPIKey")

let abTest = ABTest(name: "myABTest",
                    endAt: Date().addingTimeInterval(.day),
                    variantA: .init(indexName: "indexName1",
                                    trafficPercentage: 90,
                                    description: "a description"),
                    variantB: .init(indexName: "indexName2",
                                    trafficPercentage: 10,
                                    description: "a description"))

analyticsClient.addABTest(abTest) { result in
  if case .success(let response) = result {
    print("Response: \(response)")
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
val dayInMilliseconds = 60 * 60 * 24 * 1000
val abTest = ABTest(
    name = "myABTest",
    variantA = Variant(
        indexName = indexName1,
        trafficPercentage = 90,
        description = "a description"
    ),
    variantB = Variant(
        indexName = indexName2,
        trafficPercentage = 10,
        description = "a description"
    ),
    endAt = ClientDate(Time.getCurrentTimeMillis() + dayInMilliseconds)
)

clientAnalytics.addABTest(abTest)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
var abTest = new ABTest
{
    Name = "myABTest",
    Variants = new List<Variant>
    {
        new Variant
        {
            Index = "indexName1",
            TrafficPercentage = 90,
            Description = "a description"
        },
        new Variant
        {
            Index = "indexName1-alt",
            TrafficPercentage = 10,
            Description = "a description"
        }
    },
    EndAt = DateTime.UtcNow.AddDays(1)
};

// Add a new A/B Test
AnalyticsClient analytics = new AnalyticsClient("YourApplicationID", "YourWriteAPIKey");
analytics.AddABTest(abtest);

// Asynchronous
await analytics.AddABTestAsync(abtest);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
OffsetDateTime utcNow = 
  OffsetDateTime.now(ZoneOffset.UTC)
  .withNano(0)
  .withSecond(0);

ABTest abtest = new ABTest(
        "myABTest",
        Arrays.asList(
                new Variant("indexName1", 90, "a description"),
                new Variant("indexName1-alt", 10, null)),
        utcNow.plusDays(1));

// Add a new AB Test
AnalyticsClient analytics = 
DefaultAnalyticsClient.create("YourApplicationID", "YourWriteAPIKey");

analytics.addABTest(abtest);

// Asynchronous
analytics.addABTestAsync(abtest);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
abTest := analytics.ABTest{
	Name: "myABTest",
	Variants: []analytics.Variant{
		{
			Index:             "indexName1",
			TrafficPercentage: 90,
			Description:       "a description",
		},
		{
			Index:             "indexName1-alt",
			TrafficPercentage: 10,
		},
	},
	EndAt: time.Now().Truncate(time.Hour).Add(24 * time.Hour),
}

client := analytics.NewClient("YourApplicationID", "YourWriteAPIKey")
res, err := client.AddABTest(abTest)

1
2
3
4
5
6
7
8
9
10
11
12
val abTest = ABTest(
  "myABTest",
  Seq(
    ABTestVariant("indexName1", 90, Some("a description")),
    ABTestVariant("indexName1-alt", 10, None)
  ),
  LocalDateTime.now().plusDays(1)
)

client.execute {
  add abTest abTest
}

Add an A/B test on a single index with custom search parameters

Copy

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
$endAt = new DateTime('tomorrow');

$abTest = [
    'name' => 'myABTest',
    'variants' => [
        ['index' => 'indexName1', 'trafficPercentage' => 90],
        [
            'index' => 'indexName1',
            'trafficPercentage' => 10,
            'customSearchParameters' => ['ignorePlurals' => true],
        ],
    ],
    'endAt' => $endAt->format('Y-m-d\TH:i:s\Z'),
];

$response = $analyticsClient->addABTest($abTest);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
tomorrow = Time.now + 24*60*60

abtest = {
  name: 'myABTest',
  variants: [
    {
      index: 'indexName1',
      trafficPercentage: 90,
      description: 'a description'
    },
    {
      index: 'indexName1',
      trafficPercentage: 10,
      customSearchParameters: {ignorePlurals: true},
    },
  ],
  endAt: tomorrow.strftime("%Y-%m-%dT%H:%M:%SZ"),
}

analytics = client.init_analytics
analytics.add_ab_test(abtest)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
const endAt = new Date();
endAt.setDate(endAt.getDate() + 1);

const abTest = {
  name: 'myABTest',
  variants: [
    {
      index: 'indexName1',
      trafficPercentage: 90
    },
    {
      index: 'indexName1',
      trafficPercentage: 10,
      description: 'a description',
      customSearchParameters: { ignorePlurals: true }
    }
  ],
  endAt: endAt.toISOString().replace(/\.[0-9]{3}/, '')
};

const analytics = client.initAnalytics({
  // optional parameters
  region: 'de',
  appId: 'YourApplicationID',
  apiKey: 'YourWriteAPIKey',
});
analytics.addABTest(abTest).then(({ abTestID }) => {
  console.log(abTestID);
});

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
end_at = datetime.date.today() + datetime.timedelta(days=1)

ab_test = {
    'name': 'myABTest',
    'variants': [
        {'index': 'indexName1', 'trafficPercentage': 90},
        {
            'index': 'indexName1', 'trafficPercentage': 10,
            'customSearchParameters': {
                'ignorePlurals': True
            }
        }
    ],
    'endAt': end_at.strftime('%Y-%m-%dT%H:%M:%SZ'),
}

analytics.add_ab_test(ab_test)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
let analyticsClient = AnalyticsClient(appID: "YourApplicationID", apiKey: "YourWriteAPIKey")

let abTest = ABTest(name: "myABTest",
                    endAt: Date().addingTimeInterval(.day),
                    variantA: .init(indexName: "indexName1",
                                    trafficPercentage: 90,
                                    description: "a description"),
                    variantB: .init(indexName: "indexName2",
                                    trafficPercentage: 10,
                                    customSearchParameters: Query()
                                      .set(\.ignorePlurals, to: true)
                                    description: "a description"))

analyticsClient.addABTest(abTest) { result in
  if case .success(let response) = result {
    print("Response: \(response)")
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
val dayInMilliseconds = 60 * 60 * 24 * 1000
val abTest = ABTest(
    name = "myABTest",
    variantA = Variant(
        indexName = indexName1,
        trafficPercentage = 90,
        description = "a description"
    ),
    variantB = Variant(
        indexName = indexName1,
        trafficPercentage = 10,
        description = "a description",
        customSearchParameters = Query(ignorePlurals = IgnorePlurals.True)
    ),
    endAt = ClientDate(Time.getCurrentTimeMillis() + dayInMilliseconds)
)

clientAnalytics.addABTest(abTest)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
var abTest = new ABTest
{
    Name = "myABTest",
    Variants = new List<Variant>
    {
        new Variant
        {
            Index = "indexName1",
            TrafficPercentage = 90
        },
        new Variant
        {
            Index = "indexName1",
            TrafficPercentage = 10,
            CustomSearchParameters = new Query { IgnorePlurals = true }
        }
    },
    EndAt = DateTime.UtcNow.AddDays(1)
};

var response = analytics.AddABTest(abTest);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
OffsetDateTime utcNow = 
    OffsetDateTime.now(ZoneOffset.UTC)
    .withNano(0)
    .withSecond(0);

Variant variantWithSearchParam = new Variant("indexName1", 10, null);

variantWithSearchParam.setCustomSearchParameters(
        new Query().setIgnorePlurals(IgnorePlurals.of(true)));

ABTest abtest =
      new ABTest(
              "myABTest",
              new Variant("indexName1", 90, null), variantWithSearchParam),
              utcNow.plusDays(1));

analytics.addABTest(abtest);

// Asynchronous
analytics.addABTestAsync(abtest);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
abTest := analytics.ABTest{
	Name: "myABTest",
	Variants: []analytics.Variant{
		{
			Index:             "indexName1",
			TrafficPercentage: 90,
		},
		{
			Index:             "indexName1",
			TrafficPercentage: 10,
			CustomSearchParameters: &search.QueryParams{
				IgnorePlurals: opt.IgnorePlurals(true),
			},
		},
	},
	EndAt: time.Now().Truncate(time.Hour).Add(24 * time.Hour),
}

client := analytics.NewClient("YourApplicationID", "YourWriteAPIKey")
res, err := client.AddABTest(abTest)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
val abTest = ABTest(
  "myABTest",
  Seq(
    ABTestVariant("indexName1", 90),
    ABTestVariant("indexName1", 10,
                    customSearchParameters =
                      Some(Query(ignorePlurals = Some(IgnorePlurals.`true`)))),
  ),
  LocalDateTime.now().plusDays(1)
)

client.execute {
  add abTest abTest
}

Parameters

Parameter Description


            abTest

type: abTest object

Required

The definition of the A/B test

{
  "name": name,
  "variants": variants,
  "endAt": endAt,
  "configuration": configuration
}

➔ abTest object

Parameter	Description
`name`	type: string Required Name of the A/B test
`variants`	type: list of variant Required List of 2 variants: The base index The index to test against [ { "index": index, "description": description, "trafficPercentage": trafficPercentage }, { "index": index, "description": description, "trafficPercentage": trafficPercentage, "customSearchParameters": customSearchParameters } ]
`endAt`	type: string Optional A date to automatically end an A/B test at a specific time. The date should be in the following format: `Y-m-d\TH:i:s\Z`
`configuration`	type: configuration object Optional Configuration parameters for the A/B test. { "outliers": outliers, "emptySearch": emptySearch }

variants ➔ variant

Parameter	Description
`index`	type: string Required Index name
`trafficPercentage`	type: integer Required Percentage of the traffic that should be going to the variant. The sum of the percentage should be equal to 100.
`estimatedSampleSize`	type: integer Optional The estimated number of searches that will need to be run to achieve the desired confidence level and statistical power. A `minimumDetectableEffect` must be set in the `configuration` object for this to be used.
`customSearchParameters`	type: key/value mapping Optional Applies search parameters on a variant. This can only be used if the two variants are using the same index. Can be one or several of the following parameters: Search `queryType` `minProximity` `enableRules` `ignorePlurals` `removeStopWords` `exactOnSingleWordQuery` `advancedSyntax` `alternativesAsExact` `removeWordsIfNoResults` `sumOrFiltersScores` `distinct` Typo tolerance `typoTolerance` `minWordSizefor1Typo` `minWordSizefor2Typos` `allowTyposOnNumericTokens` `disableTypoToleranceOnAttributes` Facets `sortFacetValuesBy` Synonyms `synonyms` `replaceSynonymsInHighlight` Personalization `enablePersonalization` `personalizationImpact` Distinct `facetingAfterDistinct` Geo search `minimumAroundRadius` `aroundRadius` `aroundPrecision`
`description`	type: string Optional Description of the variant. This is useful when seeing the results in the dashboard or via the API.

➔ configuration object

Parameter	Description
`outliers`	type: outliers object Optional Configuration for outlier exclusion from metrics calculations.
`emptySearch`	type: emptySearch object Optional Configuration for empty search exclusion from metrics calculations.
`minimumDetectableEffect`	type: minimumDetectableEffect object Optional Configuration for minimum detectable effect. `estimatedSampleSize` must be set on the variants for this to be used.

configuration ➔ outliers object

Parameter	Description
`exclude`	type: boolean default: true Optional Whether to exclude outliers when calculating A/B test results. Outliers will always be excluded by default unless explicitly set to false.

configuration ➔ emptySearch object

Parameter	Description
`exclude`	type: boolean default: false Optional Whether to exclude empty searches when calculating A/B test results.

configuration ➔ minimumDetectableEffect object

Parameter Description


            size

type: float

Required

The size of the minimum detectable effect. This is the smallest relative difference between the variants that you want to be able to detect. For example, if you want to be able to detect a 10% difference between the variants, you should set this to 0.1. The size must be between 0 and 1.


            effect

type: string

Required

The effect that you want to detect. This can be one of the following:

conversionRate
clickThroughRate
purchaseRate
addToCartRate

Response

This section shows the JSON response returned by the API. Each API client encapsulates this response inside objects specific to the programming language, so that the actual response might be different. You can view the response by using the getLogs method. Don’t rely on the order of attributes in the response, as JSON doesn’t guarantee the ordering of keys in objects.

JSON format

Copy

          {
  "abTestID": 78,
  "taskID": 111885720
  "index": "atis-abtest-default",
}

        

Field	Description
`abTestID`	integer Generated Id of the A/B test.
`taskID`	integer The taskID used with the waitTask method.
`index`	string Base index name for the A/B test.

Did you find this page helpful?

Add A/B test

About this method

Examples

Add an A/B test

Add an A/B test on a single index with custom search parameters

Parameters

➔ abTest object

variants ➔ variant

➔ configuration object

configuration ➔ outliers object

configuration ➔ emptySearch object

configuration ➔ minimumDetectableEffect object

Response

JSON format

On this page