API Reference / API Methods / A/B Test / Add A/B test

Aug. 16, 2022

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

About this method

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.

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


            abTest

type: abTest object

Required

The definition of the A/B test

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

➔ abTest object


            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

variants ➔ variant

`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.
`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 sereval 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.

Response

This section shows the JSON response returned by the API. Since each language encapsulates this response inside objects specific to that language and/or implementation, the actual type in your language might differ from what’s written here. You can view the response in the logs (using the getLogs method).

JSON format

Copy

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

        

`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

Response

JSON format

On this page