Choose Variations Using Kotlin SDK
The Choose Variations call activates one or more Dynamic Yield campaigns by name and retrieves data necessary to render personalized content. Learn more about the Choose call in the Experience API guide.
Note: All Choose Variations calls are asynchronous.
Parameters
Note: Either selectorNames or selectorGroups must be provided in the request body.
Parameter | Data Structure Type | Mandatory | Description |
---|---|---|---|
selectorNames required if selectorGroups is not used | List<String> | No | A list of campaigns to choose variations for. A selector represents a technical name for a campaign. Learn more about using selectors in your campaigns. |
selectorGroups required if selectorNames is not used | List<String> | No | Call a group of selectors instead of listing each selector individually. Learn more about working with selector groups. |
selectorPreviews | List<String> | No | Campaigns to generate previews for. Learn more about enabling preview mode. |
page | Page | Yes | An object containing information about the currently viewed page. |
cart | List<CartItem> | No | A list of all items currently in the cart. For Restaurant Recommendations campaigns only. |
branchId | String | No | The unique identifier of the branch. Applies only when branch context exists and must match the IDs in the branch feed. |
dayPart (Restaurants only) | DayPart | No | Defines the period of the day the request relates to. For Restaurant Recommendations campaigns only. |
orderFulfillment | OrderFulfillment | No | The fulfillment type of the order the request relates to. Applies only when branch context exists and must match the IDs in the branch feed.</span |
pageAttributes | Map<String, PageAttribute> | No | Key-value pairs that can be used for targeting. Values can be strings or numbers. |
listedItems | List<String> | No | A list of SKUs to be presented on the page to be sorted by a Sorting Optimizer campaign. |
cuid | String | No | User identifier value. Applies only when the SDK is initialized with sharedDevice as true |
cuidType | String | No | Use this identifier type to identify users across devices (for example, customer_id, account_id, or he for SHA-256 hashed email). Note: Do not include any personal information in this ID. Applies only when the SDK is initialized with sharedDevice as true |
options | ChooseOptions | No | Request configuration parameters (report a new pageview/impression, return additional metadata). |
recsProductData | RecsProductData | No | An object with 2 parameters: * fieldFilter to specify the fields to be included in the recommendation campaign response * skusOnly to fetch only the SKUs to reduce the size of the response. See the Choose API reference for more information. |
Example
private suspend fun chooseVariationsWithAllParameters() {
var result = DYSdk.getInstance().chooseVariations(
page = Page.homePage(pageLocation = "ScreenName", pageReferrer = "otherScreenName"),
selectorNames = listOf("example-campaign-1", "example-campaign-2"),
selectorGroups = listOf("example-group"),
selectorPreviews = listOf("example-previews"),
branchId = "example-branch-id",
options = ChooseOptions(),
pageAttributes = mapOf(
"Attr1" to PageAttribute("value-1"),
"Attr2" to PageAttribute(5),
),
recsProductData = RecsProductDataOptions(),
)
}
private suspend fun chooseVariationsWithAllParameters() {
var result = DYSdk.getInstance().chooseVariations(
page = Page.homePage(pageLocation = "ScreenName", pageReferrer = "otherScreenName"),
selectorNames = listOf("example-campaign-1", "example-campaign-2"),
selectorGroups = listOf("example-group"),
selectorPreviews = listOf("example-previews"),
dayPart = DayPart.DINNER,
cart = listOf(
CartItem(
productId = "example-id", quantity = 1u, itemPrice = 5f, innerProducts = listOf(
CartInnerItem(productId = "example-id", quantity = 1u, itemPrice = 3f)
)
)
),
branchId = "example-branch-id",
options = ChooseOptions(),
pageAttributes = mapOf(
"Attr1" to PageAttribute("value-1"),
"Attr2" to PageAttribute(5),
),
recsProductData = RecsProductDataOptions(),
)
}
Return Values
class DYChooseResult(
val choices: List<Choice>? = null,
val status: ResultStatus,
val warnings: List<Warning>? = null,
val error: Exception? = null,
val rawNetworkData: RawNetworkData? = null,
)
DYChooseResult
inherits from DYResult
private suspend fun chooseVariationResult() {
var chooseResult = DYSdk.getInstance().chooseVariations(
page = Page.homePage("ScreenName"),
selectorNames = listOf("example-campaign-1", "example-campaign-2")
)
when (chooseResult.status) {
ResultStatus.SUCCESS -> {
chooseResult.choices?.forEach { choice ->
//Search for your campaign by name
}
}
ResultStatus.WARNING -> {
chooseResult.choices?.forEach { choice ->
//Search for your campaign by name
}
chooseResult.warnings?.let {
//Log the warnings
}
}
ResultStatus.ERROR -> {
chooseResult.error?.let { exception ->
//Obtain the exception object here
}
chooseResult.rawNetworkData?.let { rawNetworkData ->
//Log rawNetworkData to further investigate the error
}
}
}
}
Choice
Property | Description | Data Structure Type |
---|---|---|
id | The choice’s ID | Int |
decisionId | The decision’s ID as returned from the server | String |
name | The name of the campaign (selector) | String |
type | The choice’s type | ChoiceType (DECISION, RECS_DECISION, STORE_RECS_DECISION, SORTING_DECISION, NO_DECISION) |
variations | The campaign’s chosen variations | List<Variation> |
groups | The groups the requested campaigns belong to | List<String> |
Variation
Property | Description | Data Structure Type |
---|---|---|
id | The variation ID | Int |
analyticsMetadata | Returns additional metadata. Useful for debugging and reporting to analytics tools. | AnalyticsMetadata |
payload | Possible values: CustomJsonPayload, RecsPayload, StoreRecsPayload, SortingRecsPayload. | Payload |
title | The title of the tray served in the variation For Restaurant Recommendations campaigns only. | String |
Handling the DYResult
Property | Description | Data Structure Type |
---|---|---|
status | The Choose call's status. If the type is "WARNING," it indicates that the request was successful, but there are warnings associated with the response. | ResultStatus: SUCCESS, ERROR, WARNING |
warnings | List of warnings returned from the server. Each warning item has a code and message. | List<Warning>? |
error | Errors and exceptions | Exception? |
choices | The chosen variations returned | List<Choice>? |
rawNetworkData | Network-related data (for debugging purposes) | RawNetworkData? |
Dealing with partial success
The Dynamic Yield SDK chooseVariations call supports multiple campaigns in the same call. In a scenario where results for some of the campaigns return successfully, while there is an error for others, the result status returned is “WARNING”.
The Choice return object will contain values only for the campaigns that have returned successfully.
Campaign types
The available campaign types are: API Custom Code, API Recommendations, and Restaurant Recommendations. Each variation in the return value matches the campaign type that was determined in the campaign creation process in ExperienceOS.
API Custom Code campaigns
Custom API campaigns let you use the power of Dynamic Yield A/B testing and automatic allocation, while fully controlling how the campaigns are rendered on your app.
CustomJsonPayload
Property | Description | Data Structure Type |
---|---|---|
type | The decision type | DecisionType=DECISION |
data | The variation data | String (JSON format) |
Example
private suspend fun chooseCustomJsomVariationExample() {
var chooseResult = DYSdk.getInstance().chooseVariations(
page = Page.homePage("ScreenName"),
selectorNames = listOf("custom-json-campaign")
)
when (chooseResult.status) {
ResultStatus.SUCCESS, ResultStatus.WARNING -> {
chooseResult.choices?.firstOrNull { it.name == "custom-json-campaign" }
?.let { choice ->
if (choice.type == ChoiceType.DECISION)
//Assumming there is only one variation
(choice.variations.firstOrNull()?.payload as? CustomJsonPayload)?.let { payload ->
var data = payload.data
}
}
}
ResultStatus.ERROR -> TODO()
}
}
API Recommendations campaigns
Recommendations enable you to automatically display the most relevant items to each user.
RecsPayload
Property | Description | Data Structure Type |
---|---|---|
type | The decision type | DecisionType=RECS_DECISION |
data | The variation data | RecsData |
RecsData
Property | Description | Data Structure Type |
---|---|---|
custom | The variation custom data | String (JSON format) |
slots | A list of objects containing data for each slot | List<RecsSlot> |
Example
private suspend fun chooseRecsVariationExample() {
var chooseResult = DYSdk.getInstance().chooseVariations(
page = Page.homePage("ScreenName"),
selectorNames = listOf("recs-campaign")
)
when (chooseResult.status) {
ResultStatus.SUCCESS, ResultStatus.WARNING -> {
chooseResult.choices?.firstOrNull { it.name == "recs-campaign" }?.let { choice ->
if (choice.type == ChoiceType.RECS_DECISION)
//Assuming there is only one variation
(choice.variations.firstOrNull()?.payload as? RecsPayload)?.let { payload ->
var slots = payload.data.slots
var custom = payload.data.custom
}
}
}
ResultStatus.ERROR -> TODO()
}
}
Sorting Optimizer API campaigns
Sorting optimizer enables you to sort your category pages on your app, based on personalization criteria and business logic, to help users more easily find products that match their needs and preferences for an enhanced shopping experience that increases the likelihood of purchase.
SortingPayload
Property | Description | Data Structure Type |
---|---|---|
type | The decision type | DecisionType=SORTING_DECISION |
data | The variation data | SortingData |
SortingData
Property | Description | Data Structure Type |
---|---|---|
slots | A list of objects containing data for each slot | List<SortingRecsSlot> |
Example
private suspend fun chooseRecsVariationExample() {
var chooseResult = DYSdk.getInstance().chooseVariations(
page = Page.homePage("ScreenName"),
selectorNames = listOf("recs-campaign")
)
when (chooseResult.status) {
ResultStatus.SUCCESS, ResultStatus.WARNING -> {
chooseResult.choices?.firstOrNull { it.name == "recs-campaign" }?.let { choice ->
if (choice.type == ChoiceType.RECS_DECISION)
//Assuming there is only one variation
(choice.variations.firstOrNull()?.payload as? RecsPayload)?.let { payload ->
var slots = payload.data.slots
var custom = payload.data.custom
}
}
}
ResultStatus.ERROR -> TODO()
}
}
Restaurant Recommendations campaigns
StoreRecsPayload
Property | Description | Data Structure Type |
---|---|---|
type | The decision type | DecisionType=STORE_RECS_DECISION |
data | The variation data | StoreRecsData |
StoreRecsData
Property | Description | Data Structure Type |
---|---|---|
custom | The variation data | String (JSON format) |
slots | A list of objects containing data for each slot | List<StoreRecsSlot> |
Example
private suspend fun chooseRestaurantsRecsVariationExample() {
var chooseResult = DYSdk.getInstance().chooseVariations(
page = Page.homePage("ScreenName"),
selectorNames = listOf("qsr-recs-campaign")
)
when (chooseResult.status) {
ResultStatus.SUCCESS, ResultStatus.WARNING -> {
chooseResult.choices?.firstOrNull { it.name == "qsr-recs-campaign" }?.let { choice ->
if (choice.type == ChoiceType.STORE_RECS_DECISION)
//Assumming there is only one variation
(choice.variations.firstOrNull()?.payload as? StoreRecsPayload)?.let { payload ->
var slots = payload.data.slots
}
}
}
ResultStatus.ERROR -> TODO()
}
}
Updated 19 days ago