Upgrade Guide

This topic contains the information you need to upgrade your mobile app to the latest Oracle Responsys Mobile App Platform Cloud Service SDK, starting with the 2.10.7 SDK through the most current release.

We also recommend that you review the Release Notes and Change Log files in the Android Push IO Manager project on GitHub. These files contain SDK upgrade information and updates to the step-by-step setup instructions that may not have made the publication deadline for this document.

Upgrading your mobile app to the latest SDK

Important: You must not only obtain the SDK, but you must also re-download the pushio_config.json and add it to the correct location in your mobile app. Oracle often updates the JSON file when new features are added.

To upgrade the SDK that your mobile app is using, do the following:

  1. Obtain the SDK files from the Android SDK download page.

  2. To obtain the pushio_config.json file and add it to your mobile app, follow the instructions in Step 2: SDK Installation - Obtain Necessary Files and Add Them to Your Project.

Currently supported platforms and languages

  • Supported Android versions: Android 7 (API level 24, Nougat) and later. While the SDK itself supports Android 4.1.x and later for maximum device reach, Oracle provides support/assistance only for the 3 most recent public Android versions.

  • Supported IDE: Android Studio

  • Supported languages: Java

PushIO SDK 6.39.0 to 6.40.0

Before You Begin: Please ensure that PushIO SDK 6.40 for Android is available before using this section. You can verify the current version by going to the Android SDK download page.

PushIO SDK 6.40.0 supports the following new functionality:

Geofence and Beacon Events API: Responsys now supports geofence and beacon events. The Responsys Push SDK has added a set of open APIs that enable app developers to raise entry and exit events for geofences and beacons. You can integrate with a geofence/beacon solution of your choice, or integrate with a native geofence/beacon solution.

Once implemented, marketers will be able to use geofence and beacon events in their program orchestrations in Responsys. These location-based events will be triggered when a mobile device user enters or exits a geofence or beacon zone.

To enable this feature:

  • Your account must have the Responsys Events Interface feature enabled, which is a Controlled Availability feature. To request access to this feature, please contact your Customer Success Manager or log in to My Oracle Support and create a service request.

  • Your organization's mobile apps must be built with the 19A Responsys Push SDK (version 6.40.0) or greater, when it becomes available.

  • Your organization's mobile apps must also be integrated with your chosen solution for geofencing, or beacons, or both. Depending on your solution, integration may also involve setup by a Responsys user with access to the Responsys Events Interface.

Learn more:

mParticle Kit for Responsys SDK: As of 18D, the Oracle Responsys Push SDK supports an integration with mParticle through iOS and Android mParticle Kits, which serve as an integration layer between the Responsys and mParticle SDKs. If you use mParticle as a Customer Data Platform (CDP), this integration will enable you to forward events to mParticle for further analysis and processing.

To enable this integration: See mParticle's Android Kit and Integration Instructions.

Support for titles in Push notifications: In the 19A update, we have made an enhancement that allows marketers to design and launch push notification campaigns with titles. Marketers can use the title to compose more contextual push notifications. Such notifications catch the mobile app user's attention more effectively and can lead to better campaign performance.

Marketers can access the Title field by opening the Settings dialog located on the Responsys Push Message Designer page. The Title field supports personalization and emojis.

To enable this feature: Your organization's Android mobile apps must be built with the 19A Responsys Push SDK (version 6.40.0), when it becomes available.

Note: Some customers use a pre-6.40.0 workaround for titles on Android devices. In this workaround, the first line of the text notification before the carriage return/newline was being treated as the Push notification title. This workaround will not be supported after the mobile app is upgraded to the version 6.40.0 SDK. Marketers must use the Title field, and any first line will be treated as part of the text notification.

Support for conversion window 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 mobile app developers and marketers to define the conversion window for push conversion events that occur from within the mobile app.

Marketers and mobile app developers will be able to define the concept of a conversion window that is applicable for their business. For example, they could define the conversion window to log a conversion only if the mobile app user makes the conversion within a certain number of days of opening the push notification. They could also define the conversion window such that a conversion is logged only once for every push notification opened.

To enable this feature: You must integrate your mobile app with the 19A Responsys Push SDK (version 6.40.0) when it becomes available. You must also modify your mobile app code as needed to define custom conversion behaviors. For more details, see the Engagements & Push Conversions section.

REMINDER: Upgrade your Android Mobile App to an FCM-compliant version of the Responsys SDK

If you have not already done so, Oracle strongly recommends that you update your Android mobile apps to an FCM-compliant version of the Responsys SDK immediately. This will give your Android app users enough time to upgrade to your FCM-compliant mobile app before Google's April 11, 2019 deadline.

To upgrade your mobile app to use FCM:

Mobile App Customers: Upgrade your Android Mobile App to FCM-compliant Responsys SDK version 6.38.1 or later

Recently, Google has made some changes to their current push messaging infrastructure that will require immediate action for all of our Mobile App users. To ensure your Mobile App messaging is working as intended, we encourage you to upgrade your Android mobile app to FCM-compliant Responsys SDK version 6.38.1 or later. To help you through the upgrade, we have provided some additional details and FAQs below.

Why is this upgrade required?

Responsys and all other push messaging solutions rely on Google servers and infrastructure to deliver push notifications to Android devices.

Google has deprecated their current push messaging infrastructure, Google Cloud Messaging (GCM). Google will remove the GCM client and server APIs as soon as April 11, 2019. Google is replacing GCM with Firebase Cloud Messaging (FCM) infrastructure. All push messaging solutions must upgrade to FCM, so that they will keep receiving push notifications on Android apps.

See Time to Upgrade from GCM to FCM for the official Google communication on this upgrade.

Is Responsys SDK compliant with FCM?

The Responsys Android SDK is FCM compliant as of SDK version 6.38.1, released on October 4, 2018.

How do I upgrade my mobile app to use FCM?

By when do I need to upgrade my mobile app?

Oracle recommends that you complete the mobile app upgrade immediately. This will give your Android app users enough time to upgrade to your FCM-compliant mobile app before Google's April 11, 2019 deadline.

If your Android Mobile app users have not upgraded to your FCM-compliant mobile app by April 11, 2019, they will not receive push notification from Responsys after April 11, 2019.

PushIO SDK 6.38.0 to 6.39.0

Before You Begin: Please ensure that PushIO SDK 6.39 for Android is available before using this section. You can verify the current version by going to the Android SDK download page.

The 6.39.0 SDK includes the recent 6.38.1 SDK update for Android. The 6.38.1 SDK update added support for FCM, and it fixed an issue with In-app message window force-close in some cases.

PushIO SDK 6.39.0 supports the following new functionality:

Redesigned In-app Backend feature for supporting In-app campaigns: Oracle Responsys and the SDK have changed how In-app Messaging works for mobile apps built with the 6.39.0 and later SDK. Customers enabled for this feature can realize the following benefits:

Size of the Rich HTML creative content used in In-app campaigns is no longer limited to 3.5 KB.

In-app messages will be delivered to mobile apps on iOS devices, even if the mobile app has been "force quit" by the mobile app user. The SDK will fetch messages from Responsys every 5 minutes, store them on the device, and display them when triggered.

Implementation guidelines: If your organization has not yet integrated In-app Messaging and plans to implement a new In-app Messaging integration in its mobile app OR if your organization has already integrated In-app Messaging and are updating to SDK version 6.39.0 or later, you must use the "Redesigned In-app Backend" 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 18D/6.39.0 SDK or greater.

  3. You must turn on the feature in your code, using the SDK's setInAppFetchEnabled method.

Note for customers updating their mobile apps: If you update your mobile app to SDK version 6.39.0 or later but do not enable the "Redesigned In-app Backend" feature in your app, then this will impact the 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.

For more details, see In-app Messaging.

Message Center Direct: Mobile App Marketers will now have access to a new Mobile App Campaigns format, Message Center. The Message Center Campaign Designer will enable Marketers to send messages directly to their mobile app users’ in-app Message Centers, without requiring an accompanying Push notification. This enables Marketers to launch Message Center campaigns to mobile app users, even if users have opted-out of receiving Push notifications. Currently, mobile apps fetch Message Center messages at 2-hour intervals, so Marketers will find it best suited for communications that are not time-sensitive.

To enable this feature:

  1. Request access to this feature by contacting your Customer Success Manager or logging in to My Oracle Support and creating a service request. This feature is currently released under our Controlled Availability program.

  2. For best results and performance of Message Center, your mobile app must use the Oracle Responsys Mobile App Platform Cloud Service SDK version 6.39 (18D) or later. The 6.39 version of the SDK contains key bug fixes for this feature. Oracle recommends that your mobile app always use the latest SDK.

  3. You must turn on Message Center in your code, using the SDK's setMessageCenterEnabled method. This applies even if you are upgrading from an older SDK version to SDK version 6.39.0 or later.

For more details, see the message center section for Android.

Recording Push Notification Permission Status in Responsys for Android app users: The Android SDK now captures Push Notification Permission Status for mobile app users and communicates it to Responsys. This ensures that for each app installation on an Android device, the latest Push Notification Permission Status is reflected in the CHANNEL_PERMISSION_STATUS_ column of the App Channel List.

Whenever a Device Registration is sent from the SDK to the Responsys Platform, the latest Push Notification Status is captured in the App Channel List for the Device Record.

To enable this feature, you must update your mobile app to the 18D / 6.39.0 SDK.

Support for Firebase Cloud Messaging (FCM): For SDK version 6.38.1 and later, the SDK is compatible with FCM. Android supports only one messaging library at a time, because they will conflict otherwise. Ensure that one or the other is commented out. If you wish to use FCM libraries in your app, it is recommended that you remove the GCM library dependency.

dependencies {
    // implementation 'com.google.android.gms:play-services-gcm:15.0.1'
    implementation 'com.google.firebase:firebase-messaging:17.3.4'
}