Reporting Engagement Using Swift SDK

User engagement types include:

Impression (IMP): Reports variation impressions.
Click (CLICK ): Reports when users click a displayed variation of a custom API campaign or the widget of a Recommendation campaign.
Slot click (SLOT_CLICK): In Recommendations and Sorting Optimizer campaigns, reports exactly which product was clicked.
Slot impression (SLOT_IMP): For Restaurant Recommendation campaigns only. Reports an impression for one or more slots.
Push notification click (PN_CLICK): For Reconnect push notification campaigns only. Reports clicks on the notification.

The Mobile SDK offers two ways to report them:

Using the Choice return object from the Choose Variations call
Using the DYSdk object

Using the Choice return object methods

Using the Choice object is typically the easiest way to report a user engagement.

Reporting impressions

You can report an impression for a variation using the Choice.Variation object.

reportImpression

Returns DYResult

Parameter	description	Data Structure
branchId	The branch ID (if relevant)	String? = nil
dayPart	Define the period of the day the request relates to. Relevant only to Restaurants.	dayPart? = nil

Example

func reportImpression() async {
        let result = await DYSdk.shared().engagements.reportImpression(
            decisionId: "decisionId",
            variations: [123, 456, 789], // Optional
            branchId: "example-branch-id",
            dayPart: .dinner // Optional
        )

        switch result.status {
        case .success:
            // Handle success
            break
        case .error:
            // Handle error
            break
        case .warning:
            // Handle warning
            break
        }
    }

Note: If you previously sent a Choose Variations request with isImplicitImpressionMode set to true, do not report impressions for the returned variations. Reporting them will result in counting duplicate impressions.

Reporting clicks

You can report click for a variation using the Choice.Variation object.

reportClick

Returns DYResult

Parameter	description	Data Structure
branchId	The branch ID (if relevant)	String? = nil
dayPart	Define the period of the day the request relates to. Relevant only to Restaurants.	dayPart? = nil

Example

  func reportClickViaVariation() async {
        let chooseResult = await DYSdk.shared().choose.chooseVariations(
            selectorNames: ["campaign-name"],
            page: Page.homePage(pageLocation: "screenName")
        )

        if chooseResult.status == .success {
            if let choices = chooseResult.choices,
               let choice = choices.first(where: { $0.name == "campaign-name" }),
               let variation = choice.variations.first {
                // Assuming there is only one variation

                let resultReportClick = await variation.reportClick(
                    branchId: "example-branch-id", // Optional
                    dayPart: .dinner // Optional
                )

                switch resultReportClick.status {
                case .success:
                    // handle success
                    break
                case .error:
                    // handle errors
                    break
                case .warning:
                    // handle warnings
                    break
                }
           }
        }
    }

Reporting slot clicks

Relevant only for recommendations campaigns.

You can report a click or an impression for a slot using the Choice.RecsVariation.PayLoad.Data.Slot object.

reportClick

Returns DYResult

Parameter	description	Data Structure
branchId	The branch ID (if relevant)	String? = nil
dayPart	Define the period of the day the request relates to. Relevant only to Restaurants.	dayPart? = nil

Example

    func reportClickBySlot() async {
        let chooseResult = await DYSdk.shared().choose.chooseVariations(
            selectorNames: ["recs-campaign-name"],
            page: Page.homePage(pageLocation: "screenName")
        )

        if chooseResult.status == .success {
            if let choices = chooseResult.choices,
               let choice = choices.first(where: { $0.name == "recs-campaign-name" }),
               let recsCampaign = choice.variations.first,
               let payload = recsCampaign.payload as? RecsPayload,
               let slot = payload.data.slots.first {

                let result = await slot.reportClick(
                    branchId: "example-branch-id", // Optional
                    dayPart: .dinner // Optional
                )

                switch result.status {
                case .success:
                    // handle success
                    break
                case .error:
                    // handle errors
                    break
                case .warning:
                    // handle warnings
                    break
                }
            }
        }
    }

Reporting slot impressions

You can report an impression for one or more slots using the StoreRecsVariation object.

Relevant only for Restaurant recommendations campaigns.

Parameter	Description	Data Structure
SlotIds	The IDs of the slots to report an impression for	[String]? = nil
branchId	The ID of the branch the recommendation is for	String? = nil
dayPart	Define the period of the day the request relates to. Relevant only to Restaurants.	dayPart? = nil

Example

func reportClickStoreRecsVariation() async {
        let chooseResult = await DYSdk.shared().choose.chooseVariations(
            selectorNames: ["store-recs-campaign-name"],
            page: Page.homePage(pageLocation: "screenName")
        )

        if chooseResult.status == .success {
            if let choices = chooseResult.choices,
               let choice = choices.first(where: { $0.name == "store-recs-campaign-name" }),
               let storeRecsVariation = choice.variations.first as? StoreRecsVariation,
               let payload = storeRecsVariation.payload as? StoreRecsPayload,
               let slotId = payload.data.slots.first?.slotId {

                let resultReportClick = await storeRecsVariation.reportSlotsImpression(
                    branchId: "example-branch-id",
                    dayPart: .dinner,
                    slotsIds: [slotId] // Optional
                )

                switch resultReportClick.status {
                case .success:
                    // handle success
                    break
                case .error:
                    // handle errors
                    break
                case .warning:
                    // handle warnings
                    break
                }
            }
        }
    }

Using the DYSdk Object

You can also report engagement using the DYSdk object.

reportImpression

Returns DYResult

Parameter	Description	Data Structure
decisionId	A unique decision ID received in the Choose Variations call	String
variations	The variation ID	[Int]? = nil
branchId	The ID of the branch the recommendation is for	String? = nil
dayPart	Define the period of the day the request relates to. Relevant only to Restaurants.	dayPart? = nil

Example

func reportImpression() async {
        let result = await DYSdk.shared().engagements.reportImpression(
            decisionId: "decisionId",
            variations: [123, 456, 789], // Optional
            branchId: "example-branch-id",
            dayPart: .dinner // Optional
        )

        switch result.status {
        case .success:
            // Handle success
            break
        case .error:
            // Handle error
            break
        case .warning:
            // Handle warning
            break
        }
    }

Note: If you previously sent a Choose Variations request with isImplicitImpressionMode set to true, do not report impressions for the returned variations. Reporting them will result in duplicate impressions being counted.

reportClick

Returns DYResult

Parameter	Description	Data Structure
decisionId	A unique decision ID received in the Choose Variations call	String
variation	The variation ID	Int? = nil
branchId	The ID of the branch the recommendation is for	String? = nil
dayPart	Define the period of the day the request relates to. Relevant only to Restaurants.	dayPart? = nil

Example

 func reportClick() async {
        let result = await DYSdk.shared().engagements.reportClick(
            decisionId: "decisionId",
            variation: 1234, // Optional
            branchId: "example-branch-id",
            dayPart: .dinner // Optional
        )

        switch result.status {
        case .success:
            // Handle success
            break
        case .error:
            // Handle error
            break
        case .warning:
            // Handle warning
            break
        }
    }

reportSlotClick

Returns DYResult

Parameter	Description	Data Structure
slotId Required	The slotId as returned from the Choose Variations call. Do not use for API custom code campaigns.	String
variationId	The variation ID	Int
branchId	The ID of the branch the recommendation is for	String? = nil
dayPart	Define the period of the day the request relates to. Relevant only to Restaurants.	dayPart? = nil

Example

   func reportSlotClick() async {
        let result = await DYSdk.shared().engagements.reportSlotClick(
            variation: 123, // Optional
            slotId: "slot-id-example",
            branchId: "example-branch-id",
            dayPart: .dinner // Optional
        )

        switch result.status {
        case .success:
            // Handle success
            break
        case .error:
            // Handle error
            break
        case .warning:
            // Handle warning
            break
        }
    }

reportSlotImpression

For Restaurant Recommendations campaigns.

Returns DYResult

Parameter	Description	Data Structure
slotIds Required	The slotId as returned from the Choose Variations call. Do not use for API Custom Code campaigns.	[String]
variationId	The variation ID	[Int]? = nil
branchId	The ID of the branch the recommendation is for	String? = nil
dayPart	Define the period of the day the request relates to. Relevant only to Restaurants.	dayPart? = nil

Example

 func reportSlotsImpression() async {
        let result = await DYSdk.shared().engagements.reportSlotsImpression(
            variation: 123, // Optional
            slotsIds: ["slot-id-1", "slot-id-2"],
            branchId: "example-branch-id",
            dayPart: .dinner // Optional
        )

        switch result.status {
        case .success:
            // Handle success
            break
        case .error:
            // Handle error
            break
        case .warning:
            // Handle warning
            break
        }
    }

reportPnEngagement

For App Push Notification campaigns

Returns DYResult

Parameter	Description	Data Structure
trackingData Required	Enables Dynamic Yield to track actions attributable to the push notification. Must be extracted from the messaging provider. Learn more about the tracking link variable.	trackingData
trackingData.rri		String? = nil
trackingData.sectionID		String? = nil
trackingData.userID		String? = nil
trackingData.reqTs		String? = nil
trackingData.version		String? = nil
trackingData.events(required)		[trackingDataEvent]
trackingDataeEvent.ver		String? = nil
trackingDataeEvent.expVisitId		String? = nil
trackingDataeEvent.smech		String? = nil
trackingDataeEvent.vars		[Int]? = nil
trackingDataeEvent.exp		String? = nil
trackingDataeEvent.mech		String? = nil

func reportPnEngagement() async {
        let trackingData = TrackingData(
            rri: "rri",
            sectionID: "sectionId",
            reqTs: "reqTs",
            userID: "userId",
            version: "version",
            events: [
                TrackingDataEvent(
                    ver: "ver",
                    expVisitId: "expVisitId",
                    smech: "smech",
                    vars: [1, 2, 3],
                    exp: "exp",
                    mech: "mech"
                )
            ]
        )

        let result = await DYSdk.shared().engagements.reportPnEngagement(trackingData: trackingData)

        switch result.status {
        case .success:
            // Handle success
            break
        case .error:
            // Handle error
            break
        case .warning:
            // Handle warning
            break
        }
    }