Reporting Engagement Using Kotlin 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? = null
dayPart	Define the period of the day the request relates to. Relevant only to Restaurants.	dayPart? = null

Example

private suspend fun reportImpression() { 
    var result = DYSdk.getInstance().engagements.reportImpression( 
        decisionId = "decisionId", 
        variations = listOf(123,456,789), // optional 
        dayPart = DayPart.DINNER,// optional 
        branchId = "example-branch-id" // optional 
    ) 
 
    when (result.status) { 
        ResultStatus.SUCCESS -> TODO() 
        ResultStatus.ERROR -> TODO() 
        ResultStatus.WARNING -> TODO() 
    } 
}

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

private suspend fun reportClickViaVariation() {
    var chooseResult = DYSdk.getInstance().chooseVariations( 
        selectorNames = listOf("campaign-name"), 
        page = Page.homePage(pageLocation = "screenName") 
    ) 
    if (chooseResult.status == ResultStatus.SUCCESS) { 
        chooseResult.choices?.firstOrNull { it.name == "campaign-name" }?.variations?.firstOrNull() 
            ?.let { variation -> 
                //Assuming there is only one variation 
                var resultReportClick = variation.reportClick( 
                    branchId = "example-branch-id", //Optional 
                    dayPart = DayPart.DINNER //Optional 
                ) 
                when (resultReportClick.status) { 
                    ResultStatus.SUCCESS -> TODO() //handle success 
                    ResultStatus.ERROR -> TODO()// handle errors 
                    ResultStatus.WARNING -> TODO() //handle warnings 
                } 
               
            } 
    } 
}

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? = null
dayPart	Define the period of the day the request relates to. Relevant only to Restaurants.	dayPart? = null

Example

private suspend fun reportClickBySlot() { 
    var chooseResult = DYSdk.getInstance().chooseVariations( 
        selectorNames = listOf("recs-campaign-name"), 
        page = Page.homePage(pageLocation = "screenName") 
    ) 
    if (chooseResult.status == ResultStatus.SUCCESS) { 
        chooseResult.choices?.firstOrNull { it.name == "recs-campaign-name" }?.variations?.firstOrNull() 
            ?.let { recsCampaign -> 
                (recsCampaign.payload as? RecsPayload)?.data?.slots?.firstOrNull() 
                    ?.let { slot -> 
                        var result = slot.reportClick( 
                            branchId = "example-branch-id", //Optional 
                            dayPart = DayPart.DINNER //Optional
                        ) 
                        when (result.status) { 
                            ResultStatus.SUCCESS -> TODO() //handle success 
                            ResultStatus.ERROR -> TODO()// handle errors 
                            ResultStatus.WARNING -> TODO() //handle warnings 
                        } 
                    } 
            } 
    } 
}

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	List? = null
branchId	The ID of the branch the recommendation is for	String? = null
dayPart	Define the period of the day the request relates to. Relevant only to Restaurants.	dayPart? = null

Example

private suspend fun reportClickStoreRecsVariation() { 
    var chooseResult = DYSdk.getInstance().chooseVariations( 
        selectorNames = listOf("store-recs-campaign-name"), 
        page = Page.homePage(pageLocation = "screenName") 
    ) 
    if (chooseResult.status == ResultStatus.SUCCESS) { 
        (chooseResult.choices?.firstOrNull { it.name == "store-recs-campaign-name" }?.variations?.firstOrNull() as? StoreRecsVariation)?.let { storeRecsVariation -> 
            var slotsId = 
                (storeRecsVariation.payload as? StoreRecsPayload)?.data?.slots?.map { it.slotId } 
            slotsId?.let { 
                //Assuming there is only one variation 
                var resultReportClick = storeRecsVariation.reportSlotsImpression( 
                    slotsIds = slotsId, 
                    branchId = "example-branch-id", //Optional 
                    dayPart = DayPart.DINNER //Optional 
                ) 
                when (resultReportClick.status) { 
                    ResultStatus.SUCCESS -> TODO() //handle success 
                    ResultStatus.ERROR -> TODO()// handle errors 
                    ResultStatus.WARNING -> TODO() //handle warnings 
                } 
            } 
        } 
    } 
}

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	List? = null
branchId	The ID of the branch the recommendation is for	String? = null
dayPart	Define the period of the day the request relates to. Relevant only to Restaurants.	dayPart? = null

Example

private suspend fun reportImpression() { 
    var result = DYSdk.getInstance().engagements.reportImpression( 
        decisionId = "decisionId", 
        variations = listOf(123,456,789), // optional 
        dayPart = DayPart.DINNER,// optional 
        branchId = "example-branch-id" // optional 
    ) 
 
    when (result.status) { 
        ResultStatus.SUCCESS -> TODO() 
        ResultStatus.ERROR -> TODO() 
        ResultStatus.WARNING -> TODO() 
    } 
}

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? = null
branchId	The ID of the branch the recommendation is for	String? = null
dayPart	Define the period of the day the request relates to. Relevant only to Restaurants.	dayPart? = null

Example

private suspend fun reportClick() { 
    var result = DYSdk.getInstance().engagements.reportClick( 
        decisionId = "decisionId", 
        variation = 1234, // optional 
        dayPart = DayPart.DINNER,// optional 
        branchId = "example-branch-id" // optional 
    ) 
 
    when (result.status) { 
        ResultStatus.SUCCESS -> TODO() 
        ResultStatus.ERROR -> TODO() 
        ResultStatus.WARNING -> TODO() 
    } 
}

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? = null
branchId	The ID of the branch the recommendation is for	String? = null
dayPart	Define the period of the day the request relates to. Relevant only to Restaurants.	dayPart? = null

Example

private suspend fun reportSlotClick() { 
    var result = DYSdk.getInstance().engagements.reportSlotClick( 
        variation = 123,// optional 
        slotId = "slot-id",  
       dayPart = DayPart.DINNER,// optional 
        branchId = "example-branch-id" // optional 
    ) 
 
    when (result.status) { 
        ResultStatus.SUCCESS -> TODO() 
        ResultStatus.ERROR -> TODO() 
        ResultStatus.WARNING -> TODO() 
    } 
}

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.	List<String>
variationId	The variation ID	List<Int>? = null
branchId	The ID of the branch the recommendation is for	String? = null
dayPart	Define the period of the day the request relates to. Relevant only to Restaurants.	dayPart? = null

Example

private suspend fun reportSlotsImpression() { 
    var result = DYSdk.getInstance().engagements.reportSlotsImpression( 
        variation = 123,// optional 
        slotsIds = listOf("slot-id-1","slot-id-2"), 
        dayPart = DayPart.DINNER,// optional 
        branchId = "example-branch-id" // optional 
    ) 
 
    when (result.status) { 
        ResultStatus.SUCCESS -> TODO() 
        ResultStatus.ERROR -> TODO() 
        ResultStatus.WARNING -> TODO() 
    } 
}

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? = null
trackingData.sectionID		String? = null
trackingData.userID		String? = null
trackingData.reqTs		String? = null
trackingData.version		String? = null
trackingData.events(required)		list
trackingDataeEvent.ver		String? = null
trackingDataeEvent.expVisitId		String? = null
trackingDataeEvent.smech		String? = null
trackingDataeEvent.vars		List? = nulll
trackingDataeEvent.exp		String? = null
trackingDataeEvent.mech		String? = null

private suspend fun reportPnEngagement() { 
    var result = DYSdk.getInstance().engagements.reportPnEngagement(  
        trackingData = TrackingData( 
            rri = "rri", sectionID = "sectionId", 
            reqTs = "reqTs", userID = "userId", version = "version", 
            events = listOf( 
                TrackingDataEvent( 
                    ver = "ver", 
                    expVisitId = "expVisitId", 
                    smech = "smech", 
                    vars = listOf(1, 2, 3), 
                    exp = "exp", 
                    mech = "mech" 
                ) 
            ) 
        ) 
    ) 
    when (result.status) { 
        ResultStatus.SUCCESS -> TODO() 
        ResultStatus.ERROR -> TODO() 
        ResultStatus.WARNING -> TODO() 
    } 
}