Experiences

The Create an Experience request lets you create a new experience in a project. An experience can be either of SEGMENTED or AB_TEST type. Creating an experience also creates an empty draft version for the configuration.

To configure the permissions for your application via OAuth, include the personalize:manage scope.

{
  "name": "Australian Users Experience",
  "description": "This is the experience for Australian users.",
  "__type": "SEGMENTED"
}

In this example, we create a Segmented Experience. The __type field is used to set the type of the experience. Note that the experience in the response has a latestVersion field pointing to the draft version configuration created along with the experience.

The Get all Experiences request fetches the list of all the experiences in a project.

To configure the permissions for your application via OAuth, include the personalize:read or personalize:manage scope.

The Update an Experience request lets you update an existing experience in a project. Note that once an experience of a particular type has been created, the type cannot be changed with this request.

To configure the permissions for your application via OAuth, include the personalize:manage scope.

The Get a Single Experience request fetches a specific experience created in your project.

To configure the permissions for your application via OAuth, include the personalize:read scope.

The Delete an Experience request lets you delete an existing experience in a project.

To configure the permissions for your application via OAuth, include the personalize:manage scope.

The Create an Experience Version request lets you create a new version of an experience in a project.

Creating a new version allows you to modify the configuration of an existing active version. A version can be created with a DRAFT or ACTIVE status. A new version cannot be created if a DRAFT version already exists, in which case you can only modify the existing DRAFT version.

The request must carry the full configuration: status and variants are required. Nothing is copied from the existing version, so read the live version first and send your edited copy. Creating a version with the ACTIVE status makes it live immediately and archives the current live version (ACTIVE or PAUSED) in the same request. If a DRAFT version already exists, the request is rejected with personalize.EXPERIENCES.VERSIONS.CANNOT_CREATE_VERSION_AS_DRAFT_ALREADY_EXISTS whatever status is requested.

To configure the permissions for your application via OAuth, include the personalize:manage scope.

{
  "status": "DRAFT",
  "variants": [
    {
      "__type": "SegmentedVariant",
      "name": "Australian Continent Visitors",
      "shortUid": "0",
      "audiences": [
        "388888800000000087654321",
        "399999900000000044444444"
      ],
      "audienceCombinationType": "OR"
    }
  ]
}

In this example, we create a new DRAFT version of our segmented experience. We want to target the entire Australian continent instead of just the country, and accordingly, we also target one more audience in the variant and change the audienceCombinationType. The short UID refers to the existing variant's short UID so that we can update it.

{
  "status": "ACTIVE",
  "variants": [
    {
      "__type": "ABTestVariant",
      "name": "Control",
      "shortUid": "0",
      "trafficDistribution": 33.33
    },
    {
      "__type": "ABTestVariant",
      "name": "Purple",
      "shortUid": "1",
      "trafficDistribution": 33.33
    },
    {
      "__type": "ABTestVariant",
      "name": "Red",
      "trafficDistribution": 33.33
    }
  ],
  "variantSplit": "EQUALLY_SPLIT",
  "metrics": [
    {
      "__type": "Primary",
      "event": "244444400000000087654321",
      "name": "Click on CTA"
    }
  ],
  "targeting": {
    "audience": {
      "audiences": [
        "155555500000000012345678"
      ],
      "audienceCombinationType": "AND"
    }
  }
}

The example here is the same A/B test, however, instead of creating a DRAFT version, we're activating the version instantly. The changes in the version are instantly reflected and the existing version is ARCHIVED.

The Get all Experience Versions request fetches the list of all the versions for a given Experience.

The list of versions is sorted by the createdAt date.

To configure the permissions for your application via OAuth, include the personalize:read or personalize:manage scope.

The Update an Experience Version request lets you update an existing version of an Experience. After creating an Experience initially, an empty draft version is already created, and you can update it to modify the configuration of the Experience. Once the configuration is ready, you can activate the version by updating the status to ACTIVE. Any existing live version (ACTIVE or PAUSED) will change to ARCHIVED. You can also PAUSE an active version with this request.

The request must carry the full configuration: status and variants are required. Only a DRAFT version's configuration can be edited. On an ACTIVE or PAUSED version only the status can change, and the configuration in the request must match the stored one. To pause or resume, send the version back unchanged with the new status.

**Allowed status changes**

| From | To | Result |

|---|---|---|

| DRAFT | DRAFT | The configuration is updated. |

| DRAFT | ACTIVE | The version goes live and the previous live version becomes ARCHIVED. |

| ACTIVE | PAUSED | Visitors stop seeing the experience. |

| PAUSED | ACTIVE | The experience resumes. |

Every other change is rejected.

| Condition | Error code |

|---|---|

| Editing the configuration of an ACTIVE or PAUSED version | personalize.EXPERIENCES.VERSIONS.CANNOT_UPDATE_LOCKED_VERSION |

| Setting the status to ARCHIVED | personalize.EXPERIENCES.VERSIONS.CANNOT_MANUALLY_ARCHIVE_VERSION |

| Moving an ACTIVE or PAUSED version back to DRAFT | personalize.EXPERIENCES.VERSIONS.CANNOT_MARK_VERSION_AS_DRAFT |

| Pausing a DRAFT version | personalize.EXPERIENCES.VERSIONS.CANNOT_PAUSE_INACTIVE_VERSION |

| Updating an ARCHIVED version | personalize.EXPERIENCES.VERSIONS.CANNOT_UPDATE_ARCHIVED_VERSION |

| Activating with too few variants | personalize.EXPERIENCES.VERSIONS.INSUFFICIENT_VARIANTS_TO_ACTIVATE |

| CUSTOM_PERCENTAGE split that does not add up to 100 | personalization.VARIANT.INVALID_PERCENTAGE_SUM |

To configure the permissions for your application via OAuth, include the personalize:manage scope.

{
  "status": "DRAFT",
  "variants": [
    {
      "__type": "SegmentedVariant",
      "name": "Australian Visitors",
      "audiences": [
        "388888800000000087654321"
      ],
      "audienceCombinationType": "AND"
    }
  ]
}

In this example, we update the configuration for the Segmented Experience created previously. We're creating a variant for the visitors from Australia, with the variant targeted to the Australian audience. Notice that the shortUid is skipped for the new variant as it will be generated on the server side.

{
  "status": "ACTIVE",
  "variants": [
    {
      "__type": "ABTestVariant",
      "name": "Control",
      "trafficDistribution": 50
    },
    {
      "__type": "ABTestVariant",
      "name": "Purple",
      "trafficDistribution": 50
    }
  ],
  "variantSplit": "EQUALLY_SPLIT",
  "metrics": [
    {
      "__type": "Primary",
      "event": "244444400000000087654321",
      "name": "Click on CTA"
    }
  ]
}

Activating a version is done by updating the status to ACTIVE. Any existing active version will be ARCHIVED following the activation of a new version.

{
  "status": "PAUSED",
  "variants": [
    {
      "__type": "ABTestVariant",
      "name": "Control",
      "trafficDistribution": 50
    },
    {
      "__type": "ABTestVariant",
      "name": "Purple",
      "trafficDistribution": 50
    }
  ],
  "variantSplit": "EQUALLY_SPLIT",
  "metrics": [
    {
      "__type": "Primary",
      "event": "244444400000000087654321",
      "name": "Click on CTA"
    }
  ]
}

Pausing a version is achieved by updating the status to PAUSED. Once paused, the experience does not match any variants and will return null in the Manifest API. You can also re-activate the version again by updating it with the ACTIVE status. As with any update, the request must carry the full, unchanged configuration of the version.

The Delete an Experience Version request lets you discard the draft version of an Experience. Attempting to delete an ACTIVE, PAUSED or ARCHIVED version will return an error. Only a DRAFT version can be deleted: any other status is rejected with personalize.EXPERIENCES.VERSIONS.CANNOT_DELETE_LOCKED_VERSION. A draft can only be deleted once the experience has a live version (ACTIVE or PAUSED). Until then, any draft, including one that has been configured, is rejected with personalize.EXPERIENCES.VERSIONS.CANNOT_DELETE_ONLY_DRAFT.

To configure the permissions for your application via OAuth, include the personalize:manage scope.