Engagements & Push Conversions

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.

In this topic:

Example chart of Push Campaign metrics

With engagement metrics, you can learn if users are responding to the notifications you send. 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.

For iOS, Launch Engagements and Active Engagements are automatically handled for you. However, if you want to track other metrics like In-App Purchases, Premium Content (Video Views), Social Media Hits, or other generic activities, simply insert one of the following lines when the action occurs in-app:

In-App Purchase: 

[[PushIOManager sharedInstance] trackEngagementMetric:PUSHIO_ENGAGEMENT_METRIC_INAPP_PURCHASE];

//OR with additional properties and completionHandler

[[PushIOManager sharedInstance] trackEngagementMetric:PUSHIO_ENGAGEMENT_METRIC_INAPP_PURCHASE withProperties:@{@"key":@"value"} completionHandler:^(NSError *error, NSString *response) {

}];						
PushIOManager.sharedInstance().trackEngagementMetric(PUSHIO_ENGAGEMENT_METRIC_INAPP_PURCHASE)

//OR with additional properties and completionHandler

PushIOManager.sharedInstance().trackEngagementMetric(PUSHIO_ENGAGEMENT_METRIC_INAPP_PURCHASE, withProperties:["key":"value"]) { (error, response) in

}

Premium Content: 

[[PushIOManager sharedInstance] trackEngagementMetric:PUSHIO_ENGAGEMENT_METRIC_PREMIUM_CONTENT];

//OR with additional properties and completionHandler

[[PushIOManager sharedInstance] trackEngagementMetric:PUSHIO_ENGAGEMENT_METRIC_PREMIUM_CONTENT withProperties:@{@"key":@"value"} completionHandler:^(NSError *error, NSString *response) {

}];						
PushIOManager.sharedInstance().trackEngagementMetric(PUSHIO_ENGAGEMENT_METRIC_PREMIUM_CONTENT)

//OR with additional properties and completionHandler

PushIOManager.sharedInstance().trackEngagementMetric(PUSHIO_ENGAGEMENT_METRIC_PREMIUM_CONTENT, withProperties:["key":"value"]) { (error, response) in

}

Social Media: 

[[PushIOManager sharedInstance] trackEngagementMetric:PUSHIO_ENGAGEMENT_METRIC_SOCIAL];

//OR with additional properties and completionHandler

[[PushIOManager sharedInstance] trackEngagementMetric:PUSHIO_ENGAGEMENT_METRIC_SOCIAL withProperties:@{@"key":@"value"} completionHandler:^(NSError *error, NSString *response) {

}];						
PushIOManager.sharedInstance().trackEngagementMetric(PUSHIO_ENGAGEMENT_METRIC_SOCIAL)

//OR with additional properties and completionHandler

PushIOManager.sharedInstance().trackEngagementMetric(PUSHIO_ENGAGEMENT_METRIC_SOCIAL, withProperties:["key":"value"]) { (error, response) in

}

Other: 

[[PushIOManager sharedInstance] trackEngagementMetric:PUSHIO_ENGAGEMENT_METRIC_OTHER];

//OR with additional properties and completionHandler

[[PushIOManager sharedInstance] trackEngagementMetric:PUSHIO_ENGAGEMENT_METRIC_OTHER withProperties:@{@"key":@"value"} completionHandler:^(NSError *error, NSString *response) {

}];						
PushIOManager.sharedInstance().trackEngagementMetric(PUSHIO_ENGAGEMENT_METRIC_OTHER)

//OR with additional properties and completionHandler

PushIOManager.sharedInstance().trackEngagementMetric(PUSHIO_ENGAGEMENT_METRIC_OTHER, withProperties:["key":"value"]) { (error, response) in

}

Purchase: 

[[PushIOManager sharedInstance] trackEngagementMetric:PUSHIO_ENGAGEMENT_METRIC_PURCHASE];

//OR with additional properties and completionHandler

[[PushIOManager sharedInstance] trackEngagementMetric:PUSHIO_ENGAGEMENT_METRIC_PURCHASE withProperties:@{@"key":@"value"} completionHandler:^(NSError *error, NSString *response) {

}];						
PushIOManager.sharedInstance().trackEngagementMetric(PUSHIO_ENGAGEMENT_METRIC_PURCHASE)

//OR with additional properties and completionHandler

PushIOManager.sharedInstance().trackEngagementMetric(PUSHIO_ENGAGEMENT_METRIC_PURCHASE, withProperties:["key":"value"]) { (error, response) in

}

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 *event = [[PIOConversionEvent alloc] initWithOrderId: @"orderId123" orderTotal: 220.0 orderQuantity: 2 conversionType: <PUSHIO_ENGAGEMENT_METRIC_INAPP_PURCHASE/PUSHIO_ENGAGEMENT_METRIC_PURCHASE> customProperties: @{@"custom_key":@"custom_value"}];
  
[[PushIOManager sharedInstance] trackConversionEvent: event completionHandler: ^(NSError *error, NSString *response) {
}];						
var event =  PIOConversionEvent(orderId: "order123", orderTotal: 220.0, orderQuantity: 2, conversionType: <PUSHIO_ENGAGEMENT_METRIC_INAPP_PURCHASE/PUSHIO_ENGAGEMENT_METRIC_PURCHASE>, customProperties: ["custom_key":"custom_value"])
         
PushIOManager.sharedInstance()?.trackConversionEvent(event, completionHandler: { (error, response) in         
})

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 nil if no engagement information was fetched or the resetEngagementContext method was called.

   -(NSString *)getEngagementTimeStamp;						
    func getEngagementTimeStamp() -> String!

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 nil). 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

-(void)resetEngagementContext;
func 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

Engagement tracking can be achieved with the help of following methods:

  • trackEngagementOptions

  • TrackEngagementMetric

If trackEngagementOptions is called, then it is logged with the engagement type and options Dictionary.

Syntax

[PIOEngagement] Tracking engagement with type: [Engagement type] and push payload:[push payload]

Example

[PushIOManager] [PIOEngagement] Tracking engagement with type: launch and push payload: {
    aps =     {
        alert =         {

            body = "SampleCampaign";

            title = "iOS Testing";

        };

        badge = 1        "mutable-content" = 1;

        sound = "default.wav";

    };

    "attachment_url" = "https:/interact.responsys.net/q1/responsysimages/content/ipush/image.jpg";

    ei = "ABEguw9KQV7q5slwpSuqbq9o5q_PwEYaa33RJ5YnwZAHRI4MnaojQsHOZzhdRuC7MUTQk_kP3F8TVFeWjr_tm5JqbIY3cXgnM29ieHxSyX9VHEI9c5K7sSqIEOYtOr";

    "p_dl" = "https://www.myntra.com/";

    "p_img" = "https://interact.responsys.net/q1/responsysimages/content/ipush/image.jpg";

    "rsys_src" = orcl;

}

If there is an Engagement tracking failure due to unavailability of engagement id:

[PIOEngagement] Engagement tracking failed. Error: EngagementID not available to report the conversion.

Event created to track engagement is logged as:

[PIOEngagement] Engagement tracking event type:[Event type]

URL used for Engagement/Conversion reporting:

  • [PIOEngagement] Engagement tracking URL: [URL], parameters: [Parameters]

Example

[PIOEngagement] Engagement tracking URL: https://api.pushio.com/v2/ABEi0-x8pqaQbUemZdvmXCRb0/e/ABEpYyUEmOtDQnXdjUGvjx8kQ,

parameters: {

    di = "995363A0-CBC3-4BC7-989C-B136123068C5";      

ei="ABEguw9KQV7q5slwpSuqbq9o5q_PwEYaa33RJ5YnwZAHRI4MnaojQsHOZzhdRuC7MUT_kP3F8TVFeWjr_tm5JqbIY3cXgnM2eHxSyX9VHEI9c5K7sSqIEOYtOr";

   m = launch;

}

Response received for Engagement/Conversion Reporting:

  • [PIOEngagement] Response received for engagement - URL: [ url ] Response: [response]

Example

[PIOEngagement] Response received for engagement - URL: https://api.pushio.com/v2/ABEi0-x8pqaQbUemZdvmXCRb0/e/ABEpYyUEmOtDQnXdjUGvjx8kQ 

 Response:

If Engagement/Conversion is tracked successfully:

PIOEngagement] Engagement tracked successfully.

If tracking fails:

Syntax

[PIOEngagement] Engagement tracking failed. Error:[Error description]

Example

[PIOEngagement] Engagement tracking failed. Error: Error Domain=NSURLErrorDomain Code=-1005 "The network connection was lost."

UserInfo={_kCFStreamErrorCodeKey=53, NSUnderlyingError=0x280bd9c80 {Error Domain=kCFErrorDomainCFNetwork Code=-1005 "(null)" UserInfo={NSErrorPeerAddressKey=<CFData 0x28269f020 [0x1df228660]>{length = 16, capacity = 16, bytes = 0x100201bb17cf87200000000000000000}, _kCFStreamErrorCodeKey=53, _kCFStreamErrorDomainKey=1}}, _NSURLErrorFailingURLSessionTaskErrorKey=LocalDataTask <CE2EDA30-851F-4387-9167-1AEDFDAC7823>.<2>, _NSURLErrorRelatedURLSessionTaskErrorKey=(
    "LocalDataTask <CE2EDA30-851F-4387-9167-1AEDFDAC7823>.<2>"
), NSLocalizedDescription=The network connection was lost., NSErrorFailingURLString