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

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

NOTES:

 

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:

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:

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'
}

 


PushIO SDK 6.37.0 to 6.38.0

Before You Begin: Please ensure that PushIO SDK 6.38 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.38.0 supports the following new functionality:

New Standard Interactive Notifications: Marketers now have access to 17 new Standard Interactive Notifications when they create Push campaigns. For the interaction buttons to be present in a Push notification, the mobile app associated with the campaign must be built with the 18C/6.38.0 SDK or greater.

For more details, see Interactive Notifications.

Mobile App Console Test Push supports multiple device IDs: You can now send a single test push from the Mobile App Console to up to 10 device IDs. For details, see the Test Apps topic.

SDK crash reporting: The SDK is capable of reporting crashes that happen within the SDK back to Responsys. This feature is enabled by default. You can use the setCrashLoggingEnabled method to disable or enable this feature. For more details, see Debugging & Logging.

 


PushIO SDK 6.35.0 to 6.37.0

Before You Begin: Please ensure that PushIO SDK 6.37 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.37.0 supports the following new functionality.

Important Message Center updates: In the 18B update, the interaction between the mobile app SDK and the Responsys server has changed. The Oracle Responsys Mobile App Cloud Platform SDK (Push SDK version 6.37.0 onwards) retrieves "Message Center" messages from Responsys at fixed intervals every time a mobile app is launched. The Push SDK stores retrieved messages locally, and they are served from the local storage on the device to your mobile app on demand. Mobile apps must also use an additional method, fetchRichContentForMessage, to get the rich HTML content for individual Rich Push messages.

To learn more about implementing this feature for your Android app, see Message Center on Android.

Cross-channel conversion tracking: This optional new feature enables marketers using Responsys to evaluate how effective their marketing campaign is in driving a particular post-clickthrough action, such as making a purchase. For this feature to work, Marketers must include tracked links to the mobile app in the link tables for their Email campaigns. Mobile App Developers must provide the app links to the Marketers. They must also configure the mobile app to record the click, wait for the conversion action, and then send the conversion to Responsys. To learn more about implementing this feature for your mobile app, see Cross-channel Conversion Tracking.

NOTE: Although the Oracle Responsys product has adopted a new naming convention for its quarterly product updates, the SDK versions will retain the 6.x numbering system. However, the PushIO SDK version may skip numbers in its version naming sequence. For example, the SDK version moved from 6.33.0 to 6.35.0 in 18A, and it is 6.37.0 in 18B.

 


PushIO SDK 6.33.0 to 6.35.0

Before You Begin: Please ensure that PushIO SDK 6.35 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.35.0 supports the following new functionality:

NOTE: Although the Oracle Responsys product has adopted a new naming convention for its quarterly product updates, the SDK versions will retain the 6.x numbering system. However, the PushIO SDK version may skip numbers in its version naming sequence. The SDK version is moving from 6.33.0 to 6.35.0. The planned SDK version for 18B will be 6.37.0.

 


PushIO SDK 6.33 to 6.33.1

This section provides information about migrating your mobile application from using the 6.33 SDK to the 6.33.1 SDK. Please refer to the ChangeLog for a list of fixed issues and updates. We recommend that customers use the latest SDK version, but there is no need to upgrade if the SDK updates are not applicable for your mobile app.

No specific steps are required to migrate from 6.33 to 6.33.1. Upgrading to 6.33.1 provides:

The existing API for registration - PushIOManager.registerApp() - causes the app to display a modal prompt for requesting location access. This may not suit your app's design.

With the following new API, it is now possible to do a PushIO registration without location data:

PushIOManager.getInstance(this).registerApp( boolean useLocation );

You may find this useful in a scenario where your app would like to defer the request for location.

If you do a PushIO registration without location data, you should also do a PushIO registration with location data at a later stage when your app is ready to request location access.

 


PushIO SDK 6.31 to 6.33

This section provides information about migrating your mobile application from using the 6.31 SDK to the 6.33 SDK. Please refer to the ChangeLog for a list of fixed issues and updates. We recommend that customers use the latest SDK version, but there is no need to upgrade if the SDK updates are not applicable for your mobile app.

Responsys 6.33 Support

The 6.33 PushIO SDK update for Android supports the Responsys 6.33 release. Responsys 6.33 supports multiple Message Centers for mobile apps. See the Message Center topic for more details.

Minimum Android SDK Version

PushIO SDK now requires a minimum Android SDK version of 16. Update the build.gradle file as follows:

    android {
        defaultConfig {
            minSdkVersion 16
       }
    }

Runtime Permissions

Requesting device location shows a prompt at runtime for apps targeting Android Marshmallow (API 23) and above. See Working with System Permissions in the Android developer Training portal for more details.

Deprecated APIs

With this release, we have deprecated a few APIs and provided alternatives. The below table should help in switching to the new APIs.

Old API New API
PushIOManager.ensureRegistration( )
PushIOManager.registerApp( )
PushIOManager.getUUID( )
PushIOManager.getDeviceId( )

Deprecated APIs

With this release, we have deprecated a few APIs and provided alternatives. The below table should help in switching to the new APIs.

Old API New API
PushIOManager.ensureRegistration( ) PushIOManager.registerApp( )
PushIOManager.getUUID( ) PushIOManager.getDeviceId( )

 


PushIO SDK 6.29.1 to 6.31

The sections below provide information about migrating your mobile application from using the 6.29.1 SDK to the 6.31 SDK. Please refer to the ChangeLog for a list of fixed issues and updates. We recommend that customers use the latest SDK version, but there is no need to upgrade if the SDK updates are not applicable for your mobile app.

The 6.31.0 SDK is required for implementing the Message Center feature.

Minimum Android SDK Version

PushIO SDK now requires a minimum Android SDK version of 14 (Ice Cream Sandwich). Update the build.gradle file as follows:

    android {
        defaultConfig {
            minSdkVersion 14
       }
    }

GCM Update

The internal GCM implementation has been updated to not conflict with other libraries using GCM within your app.

As part of this change, you are required to declare the following services inside the <application> element in the AndroidManifest.xml file.

<application>
    .
    .
    .
    <service android:name="com.pushio.manager.PIOGCMRegistrationIntentService"
            android:exported="false"/>
    <service
            android:name="com.pushio.manager.PIOInstanceIDListenerService"
            android:exported="false">
      <intent-filter>
           <action android:name="com.google.android.gms.iid.InstanceID" />
      </intent-filter>
    </service>
    .
    .
    .
</application>

Also, as part of this update, the following libraries are now required in the dependencies section of your modules' build.gradle file.

dependencies {
    compile 'com.google.android.gms:play-services-location:10.2.0'    
    compile 'com.google.android.gms:play-services-gcm:10.2.0'
}

 


PushIO SDK 6.29.0 to 6.29.1

No specific steps are required to migrate from 6.29.0 to 6.29.1.

 


Push SDK Version Numbering Change

Starting in August 2016, the Oracle Push Cloud Service SDK version numbering scheme will change from 2.13.x to 6.29.x. This change aligns the SDK version number with that of its parent product. The latest SDK release for Android is always available from the PushIOManager_Android SDK download page.

No specific steps are required to migrate from 2.13.6 to 6.29.0.

 


PushIO SDK 2.12.0 through 2.13.6

 


PushIO SDK 2.11.1 to 2.12.0

It is now possible to include only the part of Google Play services library that support GCM and location. So, if you had previously added the complete Google Play services library then replace this line in build.gradle,

    compile 'com.google.android.gms:play-services:6.5.87'

with this line,

    compile 'com.google.android.gms:play-services-location:6.5.87'

 


PushIO SDK 2.11.0 to 2.11.1

No specific steps required to upgrade from 2.11.0 to 2.11.1

 


PushIO SDK 2.10.7 to 2.11.0