Experiences
Experiences help you create different variations of content pages that cater to different sections of your audience. Experiences are also versioned, so that you can make draft changes on an active version of an experience. The following requests allow you to manage the Segmented and A/B Test Experiences within a project.
Create an Experience
https://personalize-api.contentstack.com/experiencesThe 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.
Create a Segmented Experience:
{
"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.
{
"name": "CTA color test",
"description": "Test if using a warmer color on the CTA improves conversions",
"__type": "AB_TEST",
"tags": [
"campaign:black-friday",
"section:homepage"
]
}{
"shortUid": "1",
"name": "CTA color test",
"description": "Test if using a warmer color on the CTA improves conversions",
"__type": "AB_TEST",
"tags": [
"campaign:black-friday",
"section:homepage"
],
"project": "6887777b3335554698867847",
"status": "DRAFT",
"createdBy": "bxxxxxxxxxxxx3",
"updatedBy": "bxxxxxxxxxxxx6",
"referredAudiences": [],
"referredEvents": [],
"createdAt": "2024-03-13T15:39:51.645Z",
"updatedAt": "2024-03-13T15:39:51.645Z",
"uid": "6887777xxxxxxxxx98867841",
"hasDraft": true,
"latestVersion": "66d5ad0000000001412ae841",
"createdByUserName": "Jane Doe",
"updatedByUserName": "Jane Doe"
}Get all Experiences
https://personalize-api.contentstack.com/experiencesThe 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.
[
{
"shortUid": "1",
"name": "CTA color",
"description": "Use a warmer color on the CTA to improve conversion",
"__type": "AB_TEST",
"tags": [
"campaign:black-friday",
"section:homepage"
],
"project": "6887777b3335554698867847",
"status": "DRAFT",
"createdBy": "bxxxxxxxxxxxx3",
"updatedBy": "bxxxxxxxxxxxx6",
"referredAudiences": [],
"referredEvents": [],
"createdAt": "2024-03-13T15:39:51.645Z",
"updatedAt": "2024-03-14T17:00:00.000Z",
"uid": "6887777xxxxxxxxx98867841",
"hasDraft": true,
"latestVersion": "66d5ad0000000001412ae841",
"createdByUserName": "Jane Doe",
"updatedByUserName": "Jane Doe"
}
]Update an Experience
https://personalize-api.contentstack.com/experiences/{uid}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.
{
"name": "CTA color",
"description": "Use a warmer color on the CTA to improve conversion",
"__type": "AB_TEST"
}{
"shortUid": "1",
"name": "CTA color",
"description": "Use a warmer color on the CTA to improve conversion",
"__type": "AB_TEST",
"tags": [
"campaign:black-friday",
"section:homepage"
],
"project": "6887777b3335554698867847",
"status": "DRAFT",
"createdBy": "bxxxxxxxxxxxx3",
"updatedBy": "bxxxxxxxxxxxx6",
"referredAudiences": [],
"referredEvents": [],
"createdAt": "2024-03-13T15:39:51.645Z",
"updatedAt": "2024-03-14T17:00:00.000Z",
"uid": "6887777xxxxxxxxx98867841",
"hasDraft": true,
"latestVersion": "66d5ad0000000001412ae841",
"createdByUserName": "Jane Doe",
"updatedByUserName": "Jane Doe"
}Get a Single Experience
https://personalize-api.contentstack.com/experiences/{uid}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.
{
"shortUid": "1",
"name": "CTA color",
"description": "Use a warmer color on the CTA to improve conversion",
"__type": "AB_TEST",
"tags": [
"campaign:black-friday",
"section:homepage"
],
"project": "6887777b3335554698867847",
"status": "DRAFT",
"createdBy": "bxxxxxxxxxxxx3",
"updatedBy": "bxxxxxxxxxxxx6",
"referredAudiences": [],
"referredEvents": [],
"createdAt": "2024-03-13T15:39:51.645Z",
"updatedAt": "2024-03-14T17:00:00.000Z",
"uid": "6887777xxxxxxxxx98867841",
"hasDraft": true,
"latestVersion": "66d5ad0000000001412ae841",
"createdByUserName": "Jane Doe",
"updatedByUserName": "Jane Doe"
}Delete an Experience
https://personalize-api.contentstack.com/experiences/{uid}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 experience was deleted successfully
Create an Experience Version
https://personalize-api.contentstack.com/experiences/{uid}/versionsThe 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.
To configure the permissions for your application via OAuth, include the personalize:manage scope.
Create a Segmented Experience version:
{
"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.
Create an active version:
{
"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.
{
"status": "DRAFT",
"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"
}
}
}{
"uid": "9888888xxxxxxxxx89102123",
"experienceUid": "688777700000000098867841",
"__type": "AB_TEST",
"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,
"shortUid": "2"
}
],
"variantSplit": "EQUALLY_SPLIT",
"metrics": [
{
"__type": "Primary",
"event": "244444400000000087654321",
"name": "Click on CTA"
}
],
"targeting": {
"audience": {
"audiences": [
"155555500000000012345678"
],
"audienceCombinationType": "AND"
}
},
"status": "DRAFT",
"createdAt": "2024-03-15T15:39:51.645Z",
"updatedAt": "2024-03-15T15:39:51.645Z",
"createdBy": "bxxxxxxxxxxxx3",
"updatedBy": "bxxxxxxxxxxxx3",
"createdByUserName": "Jane Doe",
"updatedByUserName": "Jane Doe"
}Get all Experience Versions
https://personalize-api.contentstack.com/experiences/{uid}/versionsThe 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.
[
{
"uid": "9888888xxxxxxxxx89102123",
"experienceUid": "688777700000000098867841",
"__type": "AB_TEST",
"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,
"shortUid": "2"
}
],
"variantSplit": "EQUALLY_SPLIT",
"metrics": [
{
"__type": "Primary",
"event": "244444400000000087654321",
"name": "Click on CTA"
}
],
"targeting": {
"audience": {
"audiences": [
"155555500000000012345678"
],
"audienceCombinationType": "AND"
}
},
"status": "DRAFT",
"createdAt": "2024-03-15T15:39:51.645Z",
"updatedAt": "2024-03-15T15:39:51.645Z",
"createdBy": "bxxxxxxxxxxxx3",
"updatedBy": "bxxxxxxxxxxxx3",
"createdByUserName": "Jane Doe",
"updatedByUserName": "Jane Doe"
}
]Update an Experience Version
https://personalize-api.contentstack.com/experiences/{uid}/versions/{versionUid}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 active version's status will change to ARCHIVED. You can also PAUSE an active version with this request.
To configure the permissions for your application via OAuth, include the personalize:manage scope.
Update a Segmented Experience version:
{
"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.
Activate a version:
{
"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.
Pause a 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.
{
"status": "DRAFT",
"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"
}
]
}{
"uid": "9888888xxxxxxxxx89102123",
"experienceUid": "688777700000000098867841",
"__type": "AB_TEST",
"variants": [
{
"__type": "ABTestVariant",
"name": "Control",
"trafficDistribution": 50,
"shortUid": "0"
},
{
"__type": "ABTestVariant",
"name": "Purple",
"trafficDistribution": 50,
"shortUid": "1"
}
],
"variantSplit": "EQUALLY_SPLIT",
"metrics": [
{
"__type": "Primary",
"event": "244444400000000087654321",
"name": "Click on CTA"
}
],
"status": "DRAFT",
"createdAt": "2024-03-13T15:39:51.645Z",
"updatedAt": "2024-03-14T15:39:51.645Z",
"createdBy": "bxxxxxxxxxxxx3",
"updatedBy": "bxxxxxxxxxxxx3",
"createdByUserName": "Jane Doe",
"updatedByUserName": "Jane Doe"
}Delete an Experience Version
https://personalize-api.contentstack.com/experiences/{uid}/versions/{versionUid}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.
To configure the permissions for your application via OAuth, include the personalize:manage scope.
The Experience Version was deleted successfully