Skip to main content

​
Goal

Create a multivariate test (MVT) experiment with multiple sections and variations, then set custom (non-equal) traffic allocation across those variations.
When you create an MVT experiment with POST /experiments, Kameleoon always applies equal traffic allocation to every variation and resets any submitted locked value to false, regardless of the values you submit in mvtAllocationSettings. To set custom traffic allocation, follow the three-step flow in this tutorial: create the experiment, retrieve the generated IDs, then update the allocation with a PATCH request.
For an overview of MVT concepts (sections, variations, and combinations) and how to configure traffic allocation in the Kameleoon app, read Set up multivariate tests.

​
Requirements

  • access token
The Automation API requires an access token. Retrieve the token programmatically by following the instructions in the obtaining an access token section.
  • siteId
Retrieve the siteId directly in code with the siteCode by calling the get a site by code endpoint, or find it in the app by following the steps in Create a new experiment.

​
Key concepts

​
The reference variation

Kameleoon automatically adds one reference variation to each section you submit. The reference appears in the response as variationId: "0" within that section’s allocation entries. If you submit your own variation named Original, Kameleoon creates it as a separate, additional variation. It doesn’t identify or replace the generated reference. Only submit an explicit Original variation if you intend to test two distinct baseline variations in the same section.

​
Client-submitted IDs are temporary

The sectionId and variation id values you submit in mvtVariations only link entries within that single request: they connect each mvtAllocationSettings allocation entry to the correct section and variation before Kameleoon generates permanent IDs. Use any integers that are convenient for you. Kameleoon discards the submitted values and replaces them with its own generated sectionId and variationId values. Use the generated values (returned in the response and by a later GET request) for every subsequent request. The response doesn’t include the variation names you submitted, only the generated IDs. If you need to confirm which generated ID corresponds to which submitted name, check the experiment in the Kameleoon app.

​
Section IDs versus combination IDs

Kameleoon generates two distinct sets of IDs for an MVT experiment:
  • Section and variation IDs identify one variation within one section. Use these in mvtAllocationSettings.sectionsAllocations.
  • Combination IDs identify one full combination of variations, one per section, shown to exposed visitors. Kameleoon generates every possible combination as the Cartesian product of all sections’ variations (including the reference in each section) and returns the combination IDs in the top-level variations array and as keys in the deviations map. Use these in mvtAllocationSettings.combinationsAllocations.
Both sectionsAllocations and combinationsAllocations use the same allocation item structure (allocationPart, checked, locked, sectionId, variationId), so choose only one method:
  • Populate sectionsAllocations to allocate traffic by individual variation within each section. Kameleoon derives each combination’s share from the section-level values.
  • Populate combinationsAllocations to allocate traffic directly to specific combinations.
Because combination IDs don’t exist until Kameleoon generates them, you can’t populate combinationsAllocations in the creation request. Retrieve the generated combination IDs with a GET request, then set combinationsAllocations in a follow-up PATCH request, following the same pattern used for sectionsAllocations in this tutorial.

​
Steps

​
1. Create the experiment

Endpoint:
Example:
Response (abridged):
Notice that Kameleoon generated new sectionId and variationId values (4451, 4452, 1351293-1351296), added a reference variation (variationId: "0") to each section, and replaced the submitted allocation with an equal 0.33333334 share, resetting locked to false. Kameleoon preserves exposedPart as submitted. Continue to the next step to set the allocation you want.

​
2. Retrieve the generated IDs

If you didn’t capture the generated IDs from the create response, retrieve them with a GET request. Endpoint:
Example:
The response contains the same mvtAllocationSettings.sectionsAllocations array shown in step 1, with the generated sectionId and variationId values you need for the next step.

​
3. Set custom traffic allocation

Endpoint:
Submit mvtAllocationSettings again, this time using the generated sectionId and variationId values from step 2. Example:
Response (abridged):
The allocation now matches the values you submitted, and locked stays true. A subsequent GET request confirms the same result.

​
4. Verify the experiment

Go to the Experiments Dashboard in the Kameleoon app and open the experiment to confirm the sections, variations, and traffic allocation match what you configured.

​
Known limitations

  • Deleting large MVT experiments can time out. DELETE /experiments/{experimentId} can return a 504 Gateway Timeout error when the experiment has many combinations. A timeout doesn’t necessarily mean the delete failed: send a GET request for the same experiment ID to confirm whether it still exists before retrying the delete.