Variation

Schema, including its fields, nested structure, and relationships

Definition

A Variation represents an alternate version within a campaign. In an A/B test, for example, one variation is often the original (control), and the others are test variations. Each variation can contain multiple modifications that implement the changes for that version. Variations exist within a parent campaign.

Parent Relationship

• Parent Resource Type: Campaign

• Parent Identifier Field: $_parent_id

• Rule: The parent campaign must exist before a variation can be created. A new variation payload should reference its parent Campaign by including $_parent_id: <campaign_id>.

Payload Properties

When creating/updating a Variation, the payload includes the following fields:

• id (Integer, optional) – The variation’s unique ID. Provide this only when updating an existing variation (not needed for creation). Example: 100000 (existing variation ID).

• name (String, required) – The name of the variation. This is usually a label such as "Variation A" or "New Button Variation" to identify the variant. Example: "NewBanner" (a name for the variation).

• description (String, optional) – A description of the variation. This can be used to note what this variation entails (for internal reference). Example: "This variation changes the banner color to blue."

• traffic (Integer, required) – The traffic allocation percentage for this variation. This is an integer from 0 to 100 that indicates what portion of the campaign’s audience will see this variation. (The sum of traffic percentages across all variations in a campaign typically equals 100% for an A/B test.) Example: 15 (meaning 15% of traffic gets this variation).

• code (Object, optional) – An optional global code object for the variation. This can include global JavaScript or CSS that should run for this variation regardless of specific modifications. It has two sub-fields if used:

  • js – A JavaScript code string to execute globally for this variation.

  • css – A CSS code string to apply globally for this variation.

    If no global code is needed, this field can be omitted. Example:

  "code": {
    "js": "console.log('Hello World!')",
    "css": "p { color: red; text-align: center; }"
  }

• redirections (Object, optional) – A structure for redirection rules for this variation (used if the variation redirects users to a different URL). This is advanced and only applicable if the variation is of a type that redirects (e.g., for a redirect test). It may contain details like target URLs. If the variation involves no redirection, this can be ignored. (In the schema, this is sometimes marked as "redirections v2".)

Example Variation Payload: Creating a new variation with a name and description, allocating 14% of traffic, and including some global code:

{
  "name": "variation_name",
  "description": "Define variation description",
  "traffic": 14,
  "code": {
    "js": "console.log('Hello World!')",
    "css": "p { color: red; text-align: center; }"
  }
}

(In this example, traffic: 14 this means 14% of users would be allocated to this variation. The code object contains a JavaScript snippet and a CSS rule that apply to this variation globally.)

Response Fields

When a Variation is retrieved, it includes identifying information and some metadata in addition to the fields above:

• id (Integer) – The unique ID of the variation.

• name (String) – The variation name.

• traffic (Integer) – The traffic allocation percentage assigned to this variation (0–100).

• type (String) – The type of variation. This might indicate if it’s a normal A/B test variation or another type (common values could be "ab" or "onthefly"). If not explicitly set in payload, it defaults to the campaign’s context (for AB Tasty, "ab" is a standard A/B test variation type).

Example Variation Response:

{
  "id": 1873385,
  "name": "Variation C",
  "traffic": 20,
  "type": "onthefly"
}

Error Codes

Variations use the same set of error codes as modifications (and other resources), adjusted to the context of campaigns and variations:

• InvalidPayload – The variation data was missing required fields or had invalid values.

• ParentNotFound – The specified parent campaign was not found (e.g., the $_parent_id campaign ID is invalid).

• PermissionDenied – The user is not allowed to create or modify variations in this campaign.

• DuplicateRef – A variation with the same reference already exists (for example, a duplicate variation name in the same campaign).

• InvalidDependency – A related resource is missing (for instance, trying to create a variation in a campaign that doesn’t exist or isn’t accessible).