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:

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 pane (or General pane in newer versions of Xcode), 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.

"Enable Push Notifications on Capabilities tab screenshot"

Step 5: Implement Code

[5.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/PushIOManager.h>

[5.2] Declare the PushIOManagerDelegate in your AppDelegate.h:

@interface AppDelegate : UIResponder <UIApplicationDelegate, PushIOManagerDelegate>

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

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    // Initial setup
    [[PushIOManager sharedInstance] setDelegate:self];
    [[PushIOManager sharedInstance] didFinishLaunchingWithOptions:launchOptions];

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

    // Override point for customization after application launch.
    return YES;
}

[5.4] 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];
    }

[5.5] Implement the PushIOManager Delegate Protocol in AppDelegate.m

- (void)readyForRegistration
{
   // If this method is called back, PushIOManager has a proper device token
   // so now you are ready to register.
}

- (void)registrationSucceeded
{
   // Registration was successful
}

- (void)registrationFailedWithError:(NSError *)error statusCode:(int)statusCode
{
   // Registration failed
}

Step 6: Ready, Set, Push!

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

[6.1] Log into the Web Dashboard.

[6.2] Navigate to the Push tab

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

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

[6.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: