Engagements and Push Conversions
Oracle Push Cloud Service is the only provider that goes beyond telling you if your users are opening your app via push notifications.
In this topic:
Oracle Responsys Mobile App Platform Cloud Service is the only provider that goes beyond telling you if your users are opening your app via push notifications.
With engagement metrics, you can connect the dots between a notification and actual user behavior. Do you want to see if a push notification is trying social activity? What about premium content or in-app purchases? By understanding your push conversion, you can improve your messaging strategy and even re-target users based on user behavior.
Reporting App-Opens
By default, the app-opens are handled automatically by the SDK. If your app is handling the notification in a custom way, then it needs to report the app-open using the following API method. This code should be placed in either inside onCreate() or onStart() of the Activity that launches when the user taps on the notification.
PushIOManager.getInstance(this).trackEngagement(PushIOManager.PUSHIO_ENGAGEMENT_METRIC_LAUNCH);
Reporting Conversions
If you want to track other metrics like In-App Purchases, Premium Content (Video Views), Social Media Hits, or other generic activities, you must call trackEngagement, passing one of the PUSHIO_ENGAGEMENT_METRIC constants found in the PushIOManager, as follows:
PushIOManager.getInstance(this).trackEngagement(PushIOManager.PUSHIO_ENGAGEMENT_METRIC_PREMIUM_CONTENT);
Launch and Active Engagements are handled automatically with use of the PushIOActivityLauncher. If your app is handling the notification in a custom way, then it needs to respond to the broadcasts, as described in the Optional - Customize Incoming Push Messages and Notification Taps section of the Step-by-step Guide topic.
Otherwise, Oracle Responsys Mobile App Platform Cloud Service creates a duplicate notification.
If you decide to not use PushIOActivityLauncher for your custom notification's PendingIntent items, you must report the engagements, for example:
PushIOManager.getInstance(this).trackEngagement(PushIOManager.PUSHIO_ENGAGEMENT_METRIC_LAUNCH, new PushIOEngagementListener() {
@Override
public void onEngagementSuccess() {
}
@Override
public void onEngagementError(String errorReason) {
}
});
PushIOManager.getInstance(applicationContext).trackEngagement(PushIOManager.PUSHIO_ENGAGEMENT_METRIC_LAUNCH,
object : PushIOEngagementListener{
override fun onEngagementSuccess() {
}
override fun onEngagementError(errorReason: String?) {
}
})
Reporting Conversions
If you want to track other metrics like In-App Purchases, Premium Content (Video Views), Social Media Hits, or other generic activities, you must call trackEngagement, passing one of the PUSHIO_ENGAGEMENT_METRIC constants found in the PushIOManager, as follows:
PushIOManager.getInstance(this).trackEngagement(PushIOManager.PUSHIO_ENGAGEMENT_METRIC_PREMIUM_CONTENT, new PushIOEngagementListener() {
@Override
public void onEngagementSuccess() {
}
@Override
public void onEngagementError(String errorReason) {
}
});
PushIOManager.getInstance(applicationContext).trackEngagement(PushIOManager.PUSHIO_ENGAGEMENT_METRIC_PREMIUM_CONTENT,
object : PushIOEngagementListener{
override fun onEngagementSuccess() {
}
override fun onEngagementError(errorReason: String?) {
}
})
Here's a list of the PUSHIO_ENGAGEMENT_METRIC constants handled by the PushIOManager:
In-App Purchase:
PUSHIO_ENGAGEMENT_METRIC_INAPP_PURCHASE
Premium Content:
PUSHIO_ENGAGEMENT_METRIC_PREMIUM_CONTENT
Social Media:
PUSHIO_ENGAGEMENT_METRIC_SOCIAL
Other:
PUSHIO_ENGAGEMENT_METRIC_OTHER
Important: You must clear the EngagementId when the app goes into the background due to any user action (such as the user closing the app) or any system action (such as a phone call). To clear the EngagementId, call it once in the onStop method of your app:
PushIOManager pushIOManager = PushIOManager.getInstance(this);
pushIOManager.resetEID();
Revenue Purchase Event:
The SDK version 6.48 and above supports Revenue Purchase events. These events attribute in-app purchases to the push campaign that led the app user into the mobile app. This API accepts a PIOConversionEvent instance. The PIOConversionEvent allows PUSHIO_ENGAGEMENT_METRIC_INAPP_PURCHASE or PUSHIO_ENGAGEMENT_METRIC_PURCHASE conversionType to be reported.
Use the following API to track Revenue Purchase Events:
PIOConversionEvent conversionEvent = new PIOConversionEvent();
conversionEvent.setConversionType(PushIOManager.PUSHIO_ENGAGEMENT_METRIC_PURCHASE);
conversionEvent.setOrderId("123");
conversionEvent.setOrderAmount("100.5");
conversionEvent.setOrderQuantity("5");
PushIOManager.getInstance(this).trackConversionEvent(conversionEvent, new PIOConversionListener() {
@Override
public void onSuccess() {}
@Override
public void onFailure(Exception e) {}
});
val conversionEvent = PIOConversionEvent()
conversionEvent.conversionType = PushIOManager.PUSHIO_ENGAGEMENT_METRIC_PURCHASE
conversionEvent.orderId = "123"
conversionEvent.orderAmount = 100.5
conversionEvent.orderQuantity = 5
PushIOManager.getInstance(applicationContext).trackConversionEvent(conversionEvent,
object:PIOConversionListener{
override fun onSuccess() {
}
override fun onFailure(e: Exception?) {
}
})
Enabling conversion window support for push conversions from mobile apps
Responsys already supports a Push Conversion event, which attributes conversions inside the app to the push campaign that led the app user into the mobile app. In 19A, this has been enhanced to allow your to define the conversion window for push conversion events that occur from within the mobile app. You can also define a conversion window such that a conversion is logged only once for every push notification opened.
This section describes the methods that can help you create these custom conversion behaviors for Push conversions.
Get Engagement Timestamp
This method enables you to query the time when the user clicked or opened the Push notification. The method returns a string of the engagement timestamp in ISO 8601 format. It returns null if no engagement information was fetched or the resetEngagementContext method was called.
public String getEngagementTimestamp()
Example: If you wanted to have a conversion window of three days, you could use this method to query the time. You could then compare it with current time. If it has been fewer than three days, then raise the conversion event. If more than three days have passed, you could clear the conversion context. Once the conversion context is cleared, the SDK will not raise any further Push Conversion events, even if invoked by the app.
Reset the Engagement Context
This API enables you to reset all engagement information (to null). When you reset the engagement context, no more engagement will be reported after calling this method until: either new push notification received and opened or application is invoked from the email.
public void resetEngagementContext()
Example: When a new click occurs, any existing conversion context is cleared. Attribution is made to the most recent click that the user made. Conversion can be attributed to either an email campaign or a push campaign, depending on the last place the user clicked. If you use this method to reset the conversion context after the first click, then the SDK will not raise any further conversion events, even if invoked by the app.
Verifying Engagement Reporting
URL used for Engagement and Conversion reporting:
-
[PIOEngagement] Engagement tracking URL: [URL], parameters: [Parameters]
Example
[PIOEngagement] Engagement tracking URL: https://api.pushio.com/v2/ABEi0-x8pqWikrZdvmXCRb0/e/ABEnkj6LXGJHxSXe7EwfWf8S4, parameters: ei=ABEnadFriyxXnHTRO6x_VvWJAYXOkfX70OoQ23nN3SyO2cC7gXdOZpqaLTnCXRLVzJ7P2jHt5tTq2QcevaJnvZgw3agYQLwlg0ZKcTTkP8Wg3SB6wtN5eu-uZGd8n_&di=f74t3c90-f806-4beb-9a9c-8890f8778b71&m=iap
Using Listener
The trackEngagement() API provides a listener parameter for callbacks: PushIOEngagementListener.
Based on the response from the server, either onEngagementSuccess() or onEngagementError() is called.
You may listen for these events to verify if the engagement was reported successfully.
Using Debug Logs
In debug-logging mode, the SDK prints the following logs which might help you identify the status of engagement reporting.
Note: Messages can be filtered by: [PIOEngagement].
App is launched via push notification:
[PIOEngagement] Tracking engagement with type: launch
Engagement/Conversion tracking is logged as:
[PIOEngagement] Tracking engagement with type: iap and Parameters: {
di = "...";
ei = "...";
m = iap;
Engagement tracking failure due to unavailability of engagement ID:
[PIOEngagement] Engagement tracking failed. Error: EngagementID not available to report the conversion.
Response received for Engagement/Conversion reporting:
[PIOEngagement] Response received for engagement - Response: <response>
Engagement/Conversion is tracked successfully:
[PIOEngagement] Engagement tracked successfully.
Engagement/Conversion tracking failed:
[PIOEngagement] Engagement tracking failed. Error: <reason>
Sample push payload
An engagement and conversion sample payload resembles the following:
[PIOEngagement] Received push with payload:
[rsys_src = orcl]
[ei = ABErCamtOwb916cZIbdrEOLUWp6RQUhJt1j9k2dQkEWWc_0Fr1S_LEUgXBOPmOl1bk0skKBOrKb1PfKSCePD2_UTObL_6L56kBL71xY23lZ0jCi-hCOaI0uSYRuXWp]
[from = 537817337610]
[alert = Test]
[sound = default]
[title = Title]