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

Step-by-Step Setup Instructions

This topic provides detailed instructions for integrating your iOS mobile app with Oracle Push Cloud Service.

Before You Continue

Supported platforms and languages

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

Supported XCode versions: PushIO SDK 6.32.0 and later is supported by XCode 8.3.2 and later.

Supported languages: Objective-C and Swift.

Step 1: Initial Setup

[1.1] For your initial Oracle Push Cloud Service integration, you will want to set up an iOS Development Platform. This will allow you to use a development provisioning profile so you can easily deploy and debug on your device. This is important because push notifications are not available to be tested on the simulator.

On the Web Dashboard, click Set Up --> Add Platform --> iOS Development. You can name the platform whatever you want; however, it is best to name your platforms according to which provisioning profile (development or distribution) you are using to reduce confusion later on. Click Done. You will notice that we have generated an API Key specific to the platform you just created.

"PushIO Web Dashboard - Add Platforms screenshot"

[1.2] The next step involves creating Push SSL Certificates (known as a .PEM file) via Apple’s iOS Provisioning Portal. These certificates give us permission to speak to Apple’s servers, which ultimately communicate with your application. At this stage, you will only need to create a Development Push SSL Certificate because you aren’t ready to ship or distribute your app.

This process can be a bit tricky, so we’ve created guides dedicated solely to generating the necessary .PEM files:

In addition, we have a screencast to guide you through the .PEM process as well.

[1.3] Once you have generated the .PEM file, head back to the Push IO Web Dashboard Set Up tab, click on your iOS Development platform --> Edit --> ‘Choose File’ and upload the .PEM file you just created in the previous step.

[1.4] You're now very close to integrating Oracle Push Cloud Service with your iOS project. First, you need to download our iOS PushIOManager and a configuration file called pushio_config_debug.json.

Both downloads are available from the Set Up section of the PushIO Web Dashboard, under the iOS Development platform tab.

"Downloading the PushIO SDK files"

NOTE: You can check your pushio_config_debug.json file by opening the file in TextEdit. You should see a populated bundleId value that matches your application, as well as an apiKey value that matches what you see listed on your iOS Development Platform page.

Step 2: Add Project Files

[2.1] Locate the two files you downloaded (PushIOManager framework and the pushio_config_debug.json file) and drag them into your project. Be sure to click “Copy items into destination group’s folder” in Xcode when adding files to your project (see screenshot below). A good place to put your pushio_config_debug.json file is in the same location where your AppDelegate is stored. Likewise, the best place for the PushIOManager is in the frameworks folder of your project.

"Adding files to your iOS project screenshot"

"Adding files to your iOS project screenshot"

Note: The pushio_config_debug.json file must be included in your project for the PushIOManager to read your API Key and properly connect to the backend service.

Step 3: Add the CoreLocation Framework to Your Project

[3.1] Go to your project in the Project Navigator, then to your application target.

[3.2] In the "Summary" tab, under "Linked Frameworks and Libraries," click on the "+" sign below the list of existing frameworks and add "CoreLocation.framework" from the list that appears.

"Adding CoreLocation framework to your iOS project screenshot"

[3.3] Include the -ObjC -all_load linker flags that are required for our framework:

"Including -all_load linker flags required for your iOS project screenshot"

NOTE: Use of CoreLocation with Oracle Push Cloud Service is optional, but the framework must be included in your project even if not used.

Step 4: Enable Push Notifications

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

Ensure that when you enable Push Notifications:

"Enable Push Notifications on Capabilities tab screenshot"

Step 5: Add SQLite framework

[5.1] Go to your project in the Project Navigator, then to your application target.

[5.2] On the Summary tab, under Linked Frameworks and Libraries, click the add button ("+" sign) below the list of existing frameworks. From the list of available frameworks and libraries, add libsqlite3.0.tbd.

"Adding SQLite framework to your iOS project screenshot"

Step 6: (iOS 10) Add UserNotification framework

[6.1] Go to your project in the Project Navigator, and then to your application target.

[6.2] On the Summary tab, under Linked Frameworks and Libraries, click the add button ("+" sign) below the list of existing frameworks. From the list of available frameworks and libraries, add UserNotifications.framework.

"Adding UserNotifications framework to your iOS project screenshot"

Step 7: Implement Code

[7.1] In Xcode, copy and paste the following into your AppDelegate.h file on a separate line beneath the UIKit header import statement:

//Import PushIOManager
#import <PushIOManager/PushIOManager.h>

//iOS 10:
#import <UserNotifications/UserNotifications.h>
//Implement UserNotifications delegate to receive the notification callbacks in iOS 10.
@interface AppDelegate : UIResponder <UIApplicationDelegate,UNUserNotificationCenterDelegate>
@end
        
import PushIOManager
//For UserNotifications support
import UserNotifications
//Implement UserNotifications delegate to receive the notification callbacks in iOS 10.
class AppDelegate: UIResponder, UIApplicationDelegate, UNUserNotificationCenterDelegate{

}
        

[7.2] In your AppDelegate.m file, enable logging (in the debug console):

#ifdef DEBUG
[[PushIOManager sharedInstance] enableLogging:YES];
[[PushIOManager sharedInstance] setLogLevel:PIOLogLevelInfo]; //PIOLogLevelWarn or PIOLogLevelError
#else
[[PushIOManager sharedInstance] disableLogging];
#endif
#if DEBUG
    PushIOManager.sharedInstance().enableLogging(true);
    PushIOManager.sharedInstance().setLogLevel(PIOLogLevel.info); //PIOLogLevel.warn or PIOLogLevel.error
#else
    PushIOManager.sharedInstance().disableLogging()
#endif
        

[7.3] In your AppDelegate.m file, add the following to let the SDK know the configuration type. The configuration type tells the SDK which configuration file to read:

#ifdef DEBUG
[PushIOManager sharedInstance].configType = PIOConfigTypeDebug; //load pushio_config_debug.json
#else
[PushIOManager sharedInstance].configType = PIOConfigTypeRelease;//load pushio_config.json
#endif
#if DEBUG
    PushIOManager.sharedInstance().configType = PIOConfigType.debug; //load pushio_config_debug.json
#else
    PushIOManager.sharedInstance().configType = PIOConfigType.release;//load pushio_config.json
#endif
        

[7.4] In your AppDelegate.m file, configure the SDK:

NSString *apiKey = nil;
NSString *accountToken = nil;
#ifdef DEBUG
    apiKey = DEV_APIKEY; //Copy the apiKey value from pushio_config_debug.json
    accountToken = DEV_ACCOUNT_TOKEN; //Copy the accountToken value from pushio_config_debug.json. Assign nil if no value available.
#else
    apiKey = RELEASE_APIKEY; //Copy the apiKey value from pushio_config.json.
    accountToken = RELEASE_ACCOUNT_TOKEN;//Copy the accountToken value from pushio_config.json. Assign nil if no value available.
#endif
NSError *error = nil;
[[PushIOManager sharedInstance] configureWithAPIKey:apiKey accountToken:accountToken error:&error];
if(nil == error)
{
    NSLog(@"SDK Configured Successfully");
}
else
{
    NSLog(@"Unable to configure SDK, reason: %@", error.description);
}
var apiKey : String
var accountToken : String
//FIXME: correct the apiKey and accountToken values
#if DEBUG
    apiKey = "DEBUG_APIKEY";//Copy the apiKey value from pushio_config_debug.json
    accountToken = "DEBUG_ACCOUNT_TOKEN";//Copy the accountToken value from pushio_config_debug.json. Assign nil if no value available.
#else
    apiKey = "RELEASE_APIKEY";//Copy the apiKey value from pushio_config.json.
    accountToken = "RELEASE_ACCOUNT_TOKEN";//Copy the accountToken value from pushio_config.json. Assign nil if no value available.
#endif

do {
    try PushIOManager.sharedInstance().configure(withAPIKey: apiKey, accountToken: accountToken)
    print("PushIO Configured!!!")
}catch{
    print("Unable to configure PushIO, reason: \(error.localizedDescription)")
}
        

[7.5] Integrate PushIOManager into your application lifecycle in AppDelegate.m:

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions 
{
    // This assumes that steps [7.1, 7.2, 7.3, 7.4] above are implemented before the following is called
    [[PushIOManager sharedInstance] didFinishLaunchingWithOptions:launchOptions];

    // Requests a device token from Apple
    [[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);
            }
        }
    }];
    // Override point for customization after application launch.
    return YES;
}
// Requests a device token from Apple
PushIOManager.sharedInstance().register(forAllRemoteNotificationTypes: { (regTrackError, deviceToken) in
    if (regTrackError == nil){
        print("Device Token: \(deviceToken)")
        do{
            // Register application with SDK.
            try PushIOManager.sharedInstance().registerApp(completionHandler: { (regError, response) in
                if (regError == nil){
                    print("Registration successful")
                }
                else{
                    print("Unable to register, reason: \(regError)")
                }
            })
        }catch{
            print("Unable to track registration locally, reason: \(error)")
        }
    }
})
        

[7.6] In your AppDelegate.m file , add the following line in the -(BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions function to indicate that the AppDelegate will be containing the implementation for the UserNotification Callbacks

[UNUserNotificationCenter currentNotificationCenter].delegate= self; 
UNUserNotificationCenter.current().delegate = self
        

[7.7] Implement the Apple Push Notification Service Callbacks in AppDelegate.m:

- (void)application:(UIApplication *)application didRegisterForRemoteNotificationsWithDeviceToken:
    (NSData *)deviceToken
{
    [[PushIOManager sharedInstance]  didRegisterForRemoteNotificationsWithDeviceToken:deviceToken];
}

- (void)application:(UIApplication *)application didFailToRegisterForRemoteNotificationsWithError:(NSError *)error
{
    [[PushIOManager sharedInstance]  didFailToRegisterForRemoteNotificationsWithError:error];
}

- (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];
}

//iOS 10
-(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];
}
// didRegisterForRemoteNotificationsWithDeviceToken
func application(_ application: UIApplication, didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data) {
    PushIOManager.sharedInstance().didRegisterForRemoteNotifications(withDeviceToken: deviceToken)
}

// didFailToRegisterForRemoteNotificationsWithError
func application(_ application: UIApplication, didFailToRegisterForRemoteNotificationsWithError error: Error) {
    PushIOManager.sharedInstance().didFailToRegisterForRemoteNotificationsWithError(error)
}

// didReceiveRemoteNotification
func application(_ application: UIApplication, didReceiveRemoteNotification userInfo: [AnyHashable : Any]){
    PushIOManager.sharedInstance().didReceiveRemoteNotification(userInfo)
}

// userNotificationCenter:didReceiveNotificationResponse
@available(iOS 10.0, *)
func userNotificationCenter(_ center: UNUserNotificationCenter, didReceive response: UNNotificationResponse, withCompletionHandler completionHandler: @escaping () -> Void) {
    PushIOManager.sharedInstance().userNotificationCenter(center, didReceive: response, withCompletionHandler: completionHandler)
}

// userNotificationCenter:willPresentNotification
@available(iOS 10.0, *)
func userNotificationCenter(_ center: UNUserNotificationCenter, willPresent notification: UNNotification, withCompletionHandler completionHandler: @escaping (UNNotificationPresentationOptions) -> Void) {
    PushIOManager.sharedInstance().userNotificationCenter(center, willPresent: notification, withCompletionHandler: completionHandler)
}
        

Step 8: Ready, Set, Push!

Congratulations, you've integrated the Oracle Push Cloud Service SDK! Now it's time to test your integration.

[8.1] Log into the Web Dashboard.

[8.2] Navigate to the Push tab

[8.3] Choose All Active Devices from the Audience dropdown menu.

[8.4] Type in a message and click Send Now.

[8.5] If all went well, you should see your first true iOS push notification!

"Successful test push screenshot"

Ready for an Ad-Hoc and/or App Store Build?

Creating a push-enabled Ad-Hoc or App Store build is nearly identical to creating developer builds!

What's Next?

Now that you have completed the basic configuration and have tested push notifications, we recommend that you continue to the following topics:

Also, see our iOS FAQ for troubleshooting information and answers to general questions about PushIO SDK for iOS.