Choose Variations Using Swift 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	[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	[String]	No	Call a group of selectors instead of listing each selector individually. Learn more about working with selector groups.
page	Page	Yes	An object containing information about the currently viewed page.
selectorPreviews	[String]	No	Campaigns to generate previews for. Learn more about enabling preview mode.
dayPart (Restaurants only)	DayPart	No	Defines the period of the day the request relates to. For Restaurant Recommendations campaigns only.
cart	[CartItem]	No	A list of all items currently in the cart.
branchId	String	No	The unique identifier of the branch. Applies only when branch context exists and must match the IDs in the branch feed.
options	ChooseOptions	No	Request configuration parameters (report a new pageview/impression, return additional metadata).
pageAttributes	[String : PageAttribute]	No	Key-value pairs that can be used for targeting. Values may be strings or numbers.
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

let result = await DYSdk.shared().choose
            .chooseVariations(
                selectorNames: ["example-campaign-1", "example-campaign-2"],
                page: Page.homePage(pageLocation: "Page Location", referrer: "otherScreenName"),
                selectorGroups: ["example-group"],
                selectorPreviews: ["example-previews"],
                branchId: "example-branch-id",
                options: ChooseOptions(),
                pageAttributes: ["Attr1": PageAttribute("value-1"),
                                 "Attr2": PageAttribute(5)],
                recsProductData: RecsProductDataOptions(),
            )

let result = await DYSdk.shared().choose
            .chooseVariations(
                selectorNames: ["example-campaign-1", "example-campaign-2"],
                page: Page.homePage(pageLocation: "Page Location", referrer: "otherScreenName"),
                selectorGroups: ["example-group"],
                selectorPreviews: ["example-previews"],
                dayPart: .dinner,
                cart: [CartItem(productId: "example-id", quantity: 1, itemPrice: 5, innerProducts: [CartInnerItem(productId: "example-id", quantity: 1, itemPrice: 3)])],
                branchId: "example-branch-id",
                options: ChooseOptions(),
                pageAttributes: ["Attr1": PageAttribute("value-1"),
                                 "Attr2": PageAttribute(5)],
                recsProductData: RecsProductDataOptions(),
            )

Return Values

class DYChooseResult: DYResult {
    public let choices: [Choice]?	   
}

public class DYResult {
    public let status: ResultStatus
    public let error: Error?
    public let warnings: [Warning]?
    public let rawNetworkData: RawNetworkData?
}

DYChooseResult

inherits from DYResult

 func choose() async {
        let result = await DYSdk.shared().choose
            .chooseVariations(
                selectorNames: ["example-campaign-1", "example-campaign-2"],
                page: Page.homePage(pageLocation: "Page Location", referrer: "otherScreenName")
           			 )

        switch result.status {
        case .success:
            if let choices = result.choices {
                for choice in choices {
                    //                        ...
                }
            }

        case .error:
            if let error = result.error {
                print(error)
            }

        case .warning:
            if let choices = result.choices {
                for choice in choices {
                    //                        ...
                }
            }

            if let warnings = result.warnings {
                for warning in warnings {
                    print(warning)
                }
            }

        }
    }

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, recsDecision, storeRecsDecision, noDecision)
variations	The campaign’s chosen variations	[Variation]
groups	The groups the requested campaigns belong to	[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	Payload

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.	[Warning]?
error	Errors and exceptions	Error?
choices	The chosen variations returned	[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

 func chooseCustomJsonVariation() async throws {
        let chooseResult = await DYSdk.shared().choose.chooseVariations(
            selectorNames: ["custom-json-campaign"],
            page: Page.homePage(pageLocation: "ScreenName")
        )

        switch chooseResult.status {
        case .success, .warning:
            if let choices = chooseResult.choices,
               let customChoice = choices.first(where: { $0.name == "custom-json-campaign" }) {

                if customChoice.type == .decision {
                    // Assuming there is only one variation
                    if let firstVariation = customChoice.variations.first,
                       let payload = firstVariation.payload as? CustomJsonPayload {

                        let data = payload.data

                        // Use json data here (string)
                    }
                }
            }

        case .error:
            // Handle error case
            break
        }
    }

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	[RecsSlot]

Example

 func chooseRecsVariationExample() async throws {
        let chooseResult = await DYSdk.shared().choose.chooseVariations(
            selectorNames: ["recs-campaign"],
            page: Page.homePage(pageLocation: "ScreenName")
        )
        switch chooseResult.status {
        case .success, .warning:
            if let choices = chooseResult.choices,
               let recsChoice = choices.first(where: { $0.name == "recs-campaign" }) {
                if recsChoice.type == .recsDecision {
                    // Assuming there is only one variation
                    if let firstVariation = recsChoice.variations.first,
                       let payload = firstVariation.payload as? RecsPayload {
                        let slots = payload.data.slots
                        let custom = payload.data.custom
                        // Use slots and custom data here
                    }
                }
            }
        case .error:
            break
            // Handle error case
        }
    }

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	[StoreRecsSlot]

Example

 func chooseRestaurantsRecsVariation() async throws {
        let chooseResult = await DYSdk.shared().choose.chooseVariations(
            selectorNames: ["qsr-recs-campaign"],
            page: Page.homePage(pageLocation: "ScreenName")
        )

        switch chooseResult.status {
        case .success, .warning:
            if let choices = chooseResult.choices,
               let choice = choices.first(where: { $0.name == "qsr-recs-campaign" }) {

                if choice.type == .storeRecsDecision {
                    // Assuming there is only one variation
                    if let firstVariation = choice.variations.first,
                       let payload = firstVariation.payload as? StoreRecsPayload {

                        let slots = payload.data.slots

                        // Use slots here
                    }
                }
            }

        case .error:
            // Handle error case
            break
        }
    }