API client / Methods / A/B Test
Required API Key: any key with the setSettings ACL
Method signature
$analytics->addABTest(array abTest)

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

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,
]);

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

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);

Parameters

Parameter Description
abTest
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
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

Typo tolerance

Facets

Synonyms

Personalization

Distinct

Geo search

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
Optional

Configuration for outlier exclusion from metrics calculations.

emptySearch
Optional

Configuration for empty search exclusion from metrics calculations.

minimumDetectableEffect

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

1
2
3
4
5
{
  "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?