Oracle Help Center | Oracle Push Cloud Service (Standalone) title

Upgrade Guide

This topic contains the information you need to upgrade your mobile app to the latest Oracle Push Cloud Service SDK, starting with the 6.29.0 SDK through the most current release. It also, as needed, contains notes for updating your mobile app for iOS version changes.

We recommend that you also view the "Change Log" and "Release Notes" files for the SDK you are using. Those files are available from the PushIOManager_iOS SDK download page.


PushIO SDK 6.29.2 to 6.32.0

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

PushIO SDK 6.32.0 supports features released in Responsys versions 6.31 and 6.32. The sections below provide information about migrating your mobile application from using the 6.29.2 SDK to the 6.32.0 SDK. Migration will require changes to your mobile application's setup, code changes, and some refactoring for deprecated methods.

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.

Supported iOS versions: PushIO SDK 6.32.0 and later will support iOS 8.0 and later.

Setup Changes

For 6.32.0, make the following changes to your mobile application setup.

[1.] Add the SQLite framework to your application target:

6.32.0 uses sqlite to store the events (that is, register, engagement, unregister) and sync later. Your mobile application needs to add the sqlite3.0.tbd framework in your application target.

To add the framework:

  1. Open .xcodeproj in Xcode.
  2. Select your project from left pane.
  3. Select your application target.
  4. Select the General tab.
  5. Scroll down to Linked Frameworks and Libraries.
  6. Click + and then select libsqlite3.0.tbd from the list.

"Add SQLite framework Screenshot"

[2.] Add the UserNotifications framework:

6.32.0 works with the UserNotifications framework APIs. Your mobile application needs to add the UserNotifications framework.

To add the framework:

  1. Open .xcodeproj in Xcode.
  2. Select your project from left pane.
  3. Select your application target.
  4. Select the General tab.
  5. Scroll down to Linked Frameworks and Libraries.
  6. Click + and then select UserNotifications.framework from the list.

"Add UserNotifications framework Screenshot"

[3.] Enable the Push Notifications capability:

Your mobile application needs to add the Push Notifications capability, which you can do from the Capabilities tab of your application settings.

Ensure that when you enable Push Notifications:

"Enable PushNotification capability Screenshot"

Code Changes

For 6.32.0, make the following changes to your mobile application code.

[1.] Add Debug vs Release configuration in AppDelegate.m:

Mobile apps now control whether configuration is loaded from either pushio_config_debug.json or pushio_config.json.
Applications must set the configType to let the SDK read the suggested configuration file:

  #ifdef DEBUG
        [PushIOManager sharedInstance].configType = PIOConfigTypeDebug; //load pushio_config_debug.json
    #else
        [PushIOManager sharedInstance].configType = PIOConfigTypeRelease; //load pushio_config.json
    #endif

IMPORTANT: If your mobile app does not set the configType value, the app will not select a configuration file (pushio_config_debug.json or pushio_config.json). Without the configuration file, your app will be unable to communicate with the server, and critical functions will fail (register, fetch messages, track engagements, and the like).

[2.] Enable logging in AppDelegate.m:

With 6.32.0, setDebugLevel is discontinued. To enable logging, use the enableLogging and setLogLevel methods. Use disableLogging to disable logging.

  #ifdef DEBUG
        [[PushIOManager sharedInstance] enableLogging:YES];
        [[PushIOManager sharedInstance] setLogLevel:PIOLogLevelInfo]; //PIOLogLevelWarn or PIOLogLevelError
    #else
        [[PushIOManager sharedInstance] disableLogging];
    #endif

[3.] Implement UserNotifications framework support: Implement the UNUserNotificationCenterDelegate method in your AppDelegate.h and AppDelegate.m files, as shown below:

    //In AppDelegate.h
    #import <UserNotifications/UserNotifications.h>
    @interface AppDelegate : UIResponder <UIApplicationDelegate,UNUserNotificationCenterDelegate>
    @end

    //In AppDelegate.m
    //Set the userNotificationCenter delegate, preferably in didFinishLaunchingWithOptions
    [UNUserNotificationCenter currentNotificationCenter].delegate= self;

    -(void) userNotificationCenter:(UNUserNotificationCenter *)center
        didReceiveNotificationResponse:(UNNotificationResponse *)response
                 withCompletionHandler:(void(^)())completionHandler{
        [[PushIOManager sharedInstance] userNotificationCenter:center didReceiveNotificationResponse:response withCompletionHandler:completionHandler];
    }

    -(void) userNotificationCenter:(UNUserNotificationCenter *)center
               willPresentNotification:(UNNotification *)notification
                 withCompletionHandler:(void (^)(UNNotificationPresentationOptions options))completionHandler{
        [[PushIOManager sharedInstance] userNotificationCenter:center willPresentNotification:notification withCompletionHandler:completionHandler];
    }

Deprecated Methods

This section lists the methods are deprecated in the 6.32.0 SDK, and it provides instructions for how to adapt your mobile app code for these changes.

PushIOManagerDelegate
registerWithPushIO and registerForAllRemoteNotificationTypes

[1.] Ensure that your application implements Configure SDK with a valid APIKey and accountToken (Pass nil for accountToken if it's not applicable):

NSError *error = nil;

    [[PushIOManager sharedInstance] configureWithAPIKey:API_KEY accountToken:ACCOUNT_TOKEN error:&error];
    if(nil == error){
        NSLog(@"SDK Configured Successfully");
    }else{
        NSLog(@"Unable to configure SDK, reason: %@", error.description);
    }

[2.] Once the SDK is configured successfully, register as follows:

  [[PushIOManager sharedInstance] registerForAllRemoteNotificationTypes:^(NSError *error, NSString *deviceToken) {
        if (nil == error) {
            NSError *regTrackError = nil;
            [[PushIOManager sharedInstance] registerApp:&regTrackError completionHandler:^(NSError *regAppError, NSString *response) {
                if (nil == regAppError) {
                    NSLog(@"Application registered successfully!");
                }else{
                    NSLog(@"Unable to register application, reason: %@", regAppError.description);
                }
            }];
            if (nil == regTrackError) {
                NSLog(@"Registration locally stored successfully.");
            }else{
                NSLog(@"Unable to store registration, reason: %@", regTrackError.description);
            }
        }
    }];
unregisterFromPushIO
  NSError *error = nil;
    [[PushIOManager sharedInstance] unregisterApp:&error completionHandler:^(NSError *error, NSString *response) {
        if (nil == error) {
            NSLog(@"App unregistered successfully!");
        }else{
            NSLog(@"Unable to unregister application, reason: %@", error.description);
        }
    }];
unregisterUserID
  [[PushIOManager sharedInstance] registerUserID:nil];
isRegisteredForUserID
  NSString *userID = [[PushIOManager sharedInstance] getUserID];
registeredUserID
  NSString *userID = [[PushIOManager sharedInstance] getUserID];
pushIOUUID
  NSString *deviceID = [[PushIOManager sharedInstance] getDeviceID];
pushIOAPIKey
  NSString *apiKey = [[PushIOManager sharedInstance] getAPIKey];
pushIOAccountToken
  NSString *accountToken = [[PushIOManager sharedInstance] getAccountToken];

PushIO SDK 6.29.1 to 6.29.2

PushIO SDK 6.29.2 involves changes to Device ID persistance, which now uses the iOS Keychain. Persisting the Device ID ensures that it will stay the same across re-installs of an app on the same device, so that Responsys can use the known Device ID to update the existing App Channel List record instead of creating a new one each time.

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


PushIO SDK 6.29.0 to 6.29.1

PushIO SDK 6.29.1 supports compatibility with iOS 10 GM. No specific steps are required to migrate from 6.29.0 to 6.29.1, if your app does not support iOS10.

iOS 10 Support Notes

This section provides instructions for the two changes required for supporting iOS 10. Before you begin, ensure that you are using Push SDK 6.29.1 or later.

Setup change

On the application settings Capabilities tab, ensure that Push Notifications is enabled.

"Enable Push Notifications on Capabilities tab screenshot"

Code change for notification support

The UserNotifications framework is not supported in the most recent versions (6.29.0, 6.29.1) of the Push SDK. To support notifications for both iOS 10 and earlier versions, the application must override the following didReceiveRemoteNotification methods, as shown below. (The first method is required specifically for iOS 10, and the second method is required for supporting earlier iOS versions.)

    -(void)application:(UIApplication *)application didReceiveRemoteNotification:(NSDictionary *)userInfo{
    [[PushIOManager sharedInstance] didReceiveRemoteNotification:userInfo];
    }

    - (void)application:(UIApplication *)application didReceiveRemoteNotification:(NSDictionary *)userInfo fetchCompletionHandler:(void (^)(UIBackgroundFetchResult))completionHandler
    {
        [[PushIOManager sharedInstance] didReceiveRemoteNotification:userInfo fetchCompletionResult:UIBackgroundFetchResultNewData fetchCompletionHandler:completionHandler];
    }

Push SDK Version Numbering Change

Starting in September 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 iOS is always available from the PushIOManager_iOS SDK download page.

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


Moving from iOS8 to iOS9

inApp Messaging (Required)

As you use inAppMessaging to open the inApp dialogs in the application, you will need to update your application’s plist to handle the changes in canOpenURL. This is described in the Apple Developer video topic, Privacy and Your App.

If you're recompiling with iOS SDK 9.0, add the following to your application’s plist (replace pio-PUSH_APP_ID with your own App ID):

<key>LSApplicationQueriesSchemes</key>
<array>
    <string>
        pio-PUSHIO_APP_ID
    </string>
</array>

OR add visually (in plist) by adding LSApplicationQueriesSchemes as an array and add pio-PUSHIO_APP_ID as first item in it (replace pio-PUSH_APP_ID with your own App ID):

"iOS upgrade adding app ID to LSApplicationQueriesSchemes image"

Location Access (Optional)

If your application accesses the location capability of the PushIO SDK, you must add the following into your plist:

<key>allowsBackgroundLocationUpdates</key>
<true/>

OR add visually (in plist) by adding allowsBackgroundLocationUpdates as Boolean and set the value to YES:

"iOS upgrade allowsBackgroundLocationsUpdates image"

App Transport Security (ATS)

If you compile your app with iOS SDK 9.0, you will be affected by a new security feature called App Transport Security (ATS), which enforces best practices for secure network connections - notably, TLS 1.2 and forward secrecy. Apple offers some configuration options to leverage ATS where possible, while disabling it in places where you cannot support it.

If your In-App message or Push message contains a URL, it needs to adhere to the ATS guideline. If ATS guidelines cannot be adhered to at that URL, you can consider granting that URL a policy exception. If ATS guidelines cannot be followed, respective exceptions must be added to your your app's Info.plist.

For information about App Transport Security including details about the different exceptions which are possible, see the NSAppTransportSecurity topic on the Apple's Developer site.

To check your SSL cert details and compare them against ATS guidelines, you can use the following SSL Server Test utility: https://www.ssllabs.com/ssltest/.


Moving from iOS 7 to iOS 8

Steps for Upgrading SDKs:

[1] Make changes to your AppDelegate.m & Push IO SDK Callbacks:

Basic Push:

Use this method if utilizing basic push (without iOS's new Category feature) under the didFinishLaunchingWithOptions method:

[[PushIOManager sharedInstance] registerForAllRemoteNotificationTypes];

This callback will determine if the device is iOS 8 or below versioning, and assign notification settings accordingly. The above method should replace the previous APNs token settings code already in your app(s):

// Requests a device token from Apple
[[UIApplication sharedApplication] registerForRemoteNotificationTypes:UIRemoteNotificationTypeAlert     | UIRemoteNotificationTypeBadge | UIRemoteNotificationTypeSound];

Advanced Push (Optional) - If Using Apple's "Category" Functionality

NOTE: The below code is just an example of using Apple's Category functionality in iOS 8. There are a few ways of setting these notifications up. We suggest you read up on the new functionality directly from Apple, as well: Apple Dev: "What's New in iOS Notifications".

    if ([[[UIDevice currentDevice] systemVersion] floatValue] >= 8.0) {

    UIMutableUserNotificationAction *viewAction = [[UIMutableUserNotificationAction alloc] init];
    viewAction.identifier = @"ACCEPT";
    viewAction.title = @"Accept";
    viewAction.activationMode = UIUserNotificationActivationModeForeground;
    viewAction.destructive = NO;

    UIMutableUserNotificationAction *dismissAction = [[UIMutableUserNotificationAction alloc] init];
    dismissAction.identifier = @"DECLINE";
    dismissAction.title = @"Decline";
    dismissAction.activationMode = UIUserNotificationActivationModeBackground;
    dismissAction.destructive = YES;

    UIMutableUserNotificationCategory *category = [[UIMutableUserNotificationCategory alloc] init];
    category.identifier = @"firstcategory";
    [category setActions:[NSArray arrayWithObjects:viewAction, dismissAction, nil] forContext:UIUserNotificationActionContextDefault];

    NSSet *test = [NSSet setWithObjects:category, nil];

    UIUserNotificationType types = UIUserNotificationTypeBadge | UIUserNotificationTypeSound | UIUserNotificationTypeAlert;
    UIUserNotificationSettings *mySettings = [UIUserNotificationSettings settingsForTypes:types categories:test];
    [application registerUserNotificationSettings:mySettings];
    [application registerForRemoteNotifications];

} else {

    // To accommodate for OS below iOS 8

    [application registerForRemoteNotificationTypes:
     UIRemoteNotificationTypeBadge |
     UIRemoteNotificationTypeAlert |
     UIRemoteNotificationTypeSound];
}

[2] (Optional) Configure the Handling of Action IDs for iOS 8's New "Category" Functionality by adding the Action ID handler in your AppDelegate.m file:

- (void)application:(UIApplication *)application handleActionWithIdentifier:(NSString *)identifier forRemoteNotification:(NSDictionary *)userInfo completionHandler:(void (^)())completionHandler
{

   if ([identifier isEqualToString:@"ACCEPT"])
    {
        // Perform Accept Action
    }

    if ([identifier isEqualToString:@"DECLINE"])

    {
    // Perform Decline Action
    }

    [[PushIOManager sharedInstance] handleActionWithIdentifier:identifier forRemoteNotification:userInfo completionHandler:completionHandler];
    completionHandler();
}

[3] (Optional) Update your Info.Plist to Comply with Apple Changes to Location

Add one of two lines to your Info.plist for necessary Location support, depending on the use-case of your application:

NSLocationWhenInUseUsageDescription - "Location Description When In Use"

or

NSLocationAlwaysUsageDescription - "Location Description Always In Use"

For example,

"NSLocationWhenInUseUsageDescription setting"

[4] (Optional, Recommended) Background Push Callbacks

    // This method is called for background-only pushes
     - (void)application:(UIApplication *)application didReceiveRemoteNotification:(NSDictionary *)userInfo fetchCompletionHandler:(void (^)(UIBackgroundFetchResult))completionHandler
     {
    // You can pass this to PushIO either before or after you do any processing
    [[PushIOManager sharedInstance] didReceiveRemoteNotification:userInfo];

    // Use whatever makes sense for your application
    completionHandler(UIBackgroundFetchResultNewData);
     }

Similar to Location changes in the .plist, add a mandatory background key/pair to your Info.plist file for necessary background push support:

UIBackgroundModes - remote-notification

"Required background modes setting"

And be sure "Remote Notifications" is selected in the Capabilities section in your app's settings (Target --> Capabilities --> Background Modes):

"Background Modes app settings, Remote notifications selected"