Oracle Help Center | Oracle Responsys Mobile App Platform Cloud Service title

In-App Messaging & Rich Push

This topic provides steps for configuring your mobile app to handle In-App Messaging and Rich Push. When completed, In-App campaigns and Push campaigns with Rich Message content can be managed from within Responsys without requiring further app updates, and these messages will display properly in your mobile app.

 

About In-App Messaging and Rich Push

In-App Messaging is a great way to connect with users who are engaged with your app. It provides you an opportunity to drive conversion at a moment of your choosing. For example, during a user’s birthday week, you could provide the user with a congratulatory promotion should the user open your app. Another example might be presenting the user with a free shipping offer when the user comes into your app to check the shipping status of a previous order.

Marketers can also enhance their Push campaigns by choosing to have the mobile app open a Rich Push message when a user opens the notification. Push notifications with a Rich Push message are useful when you want to prompt a user to open the app and view the message, rather than relying on a different user action. For example, instead of relying on the user going into the app during his or her birthday week, a "Happy Birthday" push notification sent on the user's birthday could cause the user to tap the notification and display the congratulatory promotion.

 

How Does In-App Messaging Work?

Depending on the version of the SDK you are using, and that your mobile app users have installed, In-App Messaging works a bit differently.

How message delivery works for Responsys 19A / 6.40.0 SDK Update and later

Oracle Responsys and the SDK have changed how In-App Campaign Messaging works for mobile apps built with the 6.40.0 and onwards SDK versions. In 19A, we enhanced the Responsys server and SDK infrastructure to use a pull-based mechanism from the SDK instead of relying on "Silent Push Notifications". The trigger for the SDK to retrieve messages from the Responsys servers is an "App Launch" (when a user brings the app to the foreground). The SDK enforces a five minute interval between "In-App Message retrievals" from the Responsys servers. Retrieved messages are cached locally and displayed whenever an In-App event is triggered.

For example:

Some of the benefits of this feature include:

To enable this feature:

  1. You must enable must enable the "Redesigned In-app Backend" feature for your Responsys account. To request access to this feature, please contact your Customer Success Manager or log in to My Oracle Support and create a service request.

  2. You must build your mobile app with the 19A/6.40.0 SDK or greater.

How message delivery works before Responsys 19A / 6.40.0 SDK Update

For apps built with an SDK released before the 19A / 6.40.0 SDK update, In-App Messages are delivered to your app on the user’s device by Responsys via a silent push notification. (Backward compatibility is preserved for mobile app users who have not upgraded their mobile apps to those using the 6.40.0 or later SDK.) Upon receipt, the Push IO SDK saves the message content, the time range that the message is valid, and the name of the trigger that causes the message to display.

This feature was released in 18D. If your app was built with the 18D SDK, you need to enable the feature in your code, using the SDK's setInAppFetchEnabled method (as described in step 5 of the "Steps for Integrating In-App Messaging and Rich Push into Your iOS App" section below). and in 18D you needed to turn on the below step was required. In 19A, we enabled this by default in the SDK.

How it works after the message is present on the mobile device

When a user engages with the mobile app, the app has your In-App Message ready for display. Two presentation styles are supported:

"Fullscreen IAM image"

"Alert-style IAM image"

Within the Responsys In-App message designer, the presentation style is selected. The SDK takes care of displaying the message in the appropriate manner, once the trigger action occurs. Also, at that time, the message is removed from the user’s device and won’t be displayed again.

There are standard mobile app events built into the SDK, which will be triggered automatically. For example, when a user opens your app, the $ExplicitAppOpen event will be triggered.

You can also define custom triggers associated to events that occur in your mobile app code. To avoid app updates, it’s a good idea to work with your marketing team to determine what set of custom triggers should be coded into the app. For example, a commerce app might have an "add_to_cart" trigger or a game might have a "reached_level_10" trigger.

NOTE: If your application has a splashscreen, tutorial, or any other Activity that is displayed before the home/main Activity is displayed, then it is recommended to use custom triggers (step 4 in the "Steps for Integrating In-App Messaging and Rich Push into Your Android App" section of this page) instead of the above built-in triggers.

 

How Does Rich Push Work?

"Rich Push" refers to the combination of a Push notification and a rich content message. When a marketer uses the Push campaign designer to create the Push notification message, the marketer can choose a notification action of "Open Rich Message." The marketer composes the Rich Push message in HTML format and may also include images and personalization, as long as the entire Push notification does not exceed the provider's limit.

Unlike In-App Messages, which are sent silently, a Rich Push is a standard push notification that contains an action that is triggered immediately when the app user taps that notification. When the user taps the notification, the system opens the app (if it is not already open), brings it to the foreground, and then displays the Rich Push message similarly to a "splash screen."

 

Steps for Integrating In-App Messaging and Rich Push into Your Android App

As an app developer, there are a few steps you will need to take to fully integrate In-App Messaging and Rich Push into your Android app. We will cover each of these steps in detail:

  1. Set up a special PushIO URL Scheme and forward URL handling to the Push IO SDK
  2. Set up the In-App Message and Rich Push Message View
  3. Define optional custom triggers (In-App Messaging only)
  4. Enable the SDK to pre-fetch the In-App messages (In-App Messaging only - new step for 19A/6.40.0 SDK and later)

[1] Set up the URL Scheme and Forward URL Handling to the Push IO SDK

When an app event is triggered, the corresponding action is passed through inter-app communication using custom URL schemes. This section describes how your application will tell Android that it handles the URL scheme expected by the Push IO SDK, and forward handling of that URL to the Push IO SDK.

NOTE: You may have other reasons to use custom URL schemes in your app, such as supporting deep-linking to specific areas of your app. Importantly, please do not use the Push IO URL scheme for these other purposes. You may set up your own URL scheme for such purposes.

The Push IO URL scheme contains your Push IO API Key and takes the format of pio-YOUR_API_KEY.

NOTE: You can look up the Push IO API Key in the config_pushio.json file or by accessing the Mobile App Developer Console, where the API Key is displayed alongside your platforms.

The SDK will only handle a URL if it matches the Push IO URL scheme.

For your app to respond to a URL scheme, declare BroadcastReceiver com.pushio.manager.PushIOUriReceiver in your AndroidManifest.xml as follows (where YOUR_API_KEY is the API Key for your app):

    <receiver
       android:name="com.pushio.manager.PushIOUriReceiver"
       android:enabled="true"
       android:exported="false">
       <intent-filter>
          <action android:name="android.intent.action.VIEW" />
          <category android:name="android.intent.category.DEFAULT" />
          <data android:scheme="pio-YOUR_API_KEY" />
       </intent-filter>
    </receiver>

[2] Set up the In-App Message and Rich Push Message View

To show an In-App message or Rich Push message on Android, you will need to declare the following elements in the AndroidManifest.xml file,

   <uses-permission android:name="${applicationId}.permission.RSYS_SHOW_IAM"/>

    <permission
       android:name="${applicationId}.permission.RSYS_SHOW_IAM"
       android:protectionLevel="signature" />

This permission will ensure that only your app (or apps signed with the same certificate as your app) may display the In-App Message/Rich Push content.

   <activity android:name="com.pushio.manager.iam.ui.PushIOMessageViewActivity"
    android:theme="@android:style/Theme.Translucent.NoTitleBar"
    android:permission="${applicationId}.permission.RSYS_SHOW_IAM">

    <intent-filter>
        <action android:name="android.intent.action.VIEW" />
        <category android:name="android.intent.category.DEFAULT" />
        <category android:name="android.intent.category.BROWSABLE" />
        <data android:scheme="pio-YOUR_API_KEY" />
    </intent-filter>

   </activity>

This Activity receives the In-App message or Rich Push message from the Push IO SDK and displays it accordingly.

[3] Define Custom Triggers (In-App Messaging only)

As described earlier, In-App messages are displayed when the associated trigger occurs in your app. You can also develop custom triggers, which are named mobile app events that you track in the code. These triggers are activated when the user takes a specific action in your mobile app. Custom trigger names are case sensitive and they should not start with a "$", which is reserved namespace for standard triggers.

For example, perhaps you want to define a custom trigger for when the user visits the "Sign In" page of your app. This might give your marketing team an opportunity to show an In-App message articulating the benefits of signing in. In this example, you would define the custom trigger like this:

PushIOManager.getInstance(getApplicationContext()).trackEvent("signup_page");

Your Responsys Account Administrator needs to know the case-sensitive name of the custom trigger, so that they can be configured. The Responsys Account Admin must go to Account > Manage Mobile App Configuration Page to add the custom triggers for your mobile app. This step is required for the custom triggers to be available within the Responsys In-App Campaign Workbook.

In the above example, you tell your Responsys Account Administrator that when a user enters the app's sign-in page, the custom trigger signup_page is activated.

[4] Enable SDK to pre-fetch the In-App Messages (for mobile apps built with the SDK version 18D/6.39.0)

IMPORTANT: Before you begin, ensure that the "Redesigned In-app Backend" feature is enabled for your account. If you update your mobile app to SDK version 6.40.0 or later, but do not enable the "Redesigned In-app Backend" feature in your app, then this will impact your marketers' ability to target all mobile app users immediately once you finally enable the "Redesigned In-app Backend" feature. Mobile app users will have to update their app to the app version that implements "Redesigned In-app Backend" feature before In-app Messages can be delivered to them.

If your app is built with the SDK version 19A/6.40.0 or greater: By default, the SDK is capable of fetching In-App Messages from Responsys after an In-App Message campaign launches. Thus, when an In-App trigger happens in the mobile app, messages are retrieved from the In-App Messages and cached locally.

If your app is built with the SDK version 18D/6.39.0: The setInAppFetchEnabled(boolean inAppFetchEnabled) API needs to be enabled for your app to pre-fetch In-App Messages.

To enable this feature, the application should call the setInAppFetchEnabled(boolean inAppFetchEnabled) API.

PushIOManager.getInstance(getApplicationContext()).setInAppFetchEnabled(true);

Parameter : Flag for enabling or disabling the InApp pull/fetch feature If true, the In-App Message list would be fetched from the server by the SDK. If set to false, it will work as the original In-App Message feature.

Troubleshooting your In-App Message Implementation using SDK Logs

If you are experiencing issues with In-App messages, check your SDK logs to determine the cause. Use the following sample SDK logs to determine what your issue might be.

SDK Event SDK Log Example
App launch happened, but the In-App fetch request cannot be made to Responsys because the 5 minute interval rule is not met.
PIOIAMM fIAM Skipping fetch...
                
In-App fetch request made to Responsys.
PIOIAMM fIAM fetching messages
                
In-App fetch response received from Responsys.
PIOIAMReqM oS IAM Received Successfully
                
No messages available for a user.
{
  "event_actions": [
    
  ],
  "next_req_time": "2019-10-04T09:50:43Z"
}
Messages are available for a user.
{
  "event_actions": [
    {
      "ei": "ABEpAGqW-UBXAc3QM_JJBBpyCqmYomZPk3P5JfFkXOH6wiReKY21uP3_COy88",
      "p_event_action": {
        "start_ts": "2019-02-11T10:49:15Z",
        "event_type": "$ExplicitAppOpen",
        "action_uri": "pio-ABEgGFd_CNo9NOL_87c6k2GzI://show_iam?style=fullscreen&url=",
        "expiry_ts": "2019-02-18T10:49:15Z"
      }
    }
  ],
  "next_req_time": "2019-02-12T05:53:05Z"
}