This topic provides detailed instructions for integrating your iOS mobile app with Oracle Push Cloud Service.
Before You Continue
New developers: Follow the steps in this section if you are new to Oracle Push Cloud Service and you are adding the SDK to your mobile app project for the first time.
Current developers: If you have already integrated the Oracle Push Cloud Service SDK to your mobile app for a previous release, use the instructions in the Upgrade Guide topic. The Upgrade Guide topic contains information about changes needed to your mobile app for SDK upgrades and for iOS upgrades.
New and current developers: Review the "Release Notes" and "Change Log" files in the iOS 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.
Supported platforms and languages
Supported iOS versions: PushIO SDK 6.38.0 and later will support iOS 9.0 and later.
Supported XCode versions: PushIO SDK 6.38.0 and later is supported by XCode 9.0.x and later.
Supported languages: Objective-C and Swift.
The Oracle Push Cloud Service SDK does not support using cross-platform mobile application development frameworks, such as Cordova or Xamarin.
Oracle only supports the use of Oracle Push Cloud Service SDK in mobile apps. We strongly recommend not using other vendors' SDKs in the same mobile app as the Oracle Push Cloud Service SDK, because we do not support mobile apps configured with push SDKs from other vendors.
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.
[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:
[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] Next, 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.
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.
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.
[3.3] Include the -ObjC -all_load linker flags that are required for our framework:
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:
Add the Push Notifications feature to your app id.
Add the Push Notifications entitlement to your entitlements file
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.
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.
Step 7: Add WebKit framework
[7.1] Go to your project in the Project Navigator, and then to your application target.
[7.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 WebKit.framework.
Step 8: Implement Code
[8.1] In Xcode, copy and paste the following into your AppDelegate.h file on a separate line beneath the UIKit header import statement:
[8.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
[9.3] Choose All Active Devices from the Audience dropdown menu.
[9.4] Type in a message and click Send Now.
[9.5] If all went well, you should see your first true iOS push notification!
Separate Opt-in for Push (Pre-permission Messaging)
If you want to delay the system prompt for push notification permission but want to register the application with SDK separately, now there are additional/separate methods provided to achieve it.
NOTE: The methods described in this section are available only when using the 6.33 PushIO SDK for iOS.
Configure and Register
The following method can be used to both configure the SDK and register with the Server by supplying a valid
apiKey and accountToken. The completion handler is called when the registration is finished.
Download and add your iOS Distribution pushio_config.json file to your project. This is the Distribution config file and will co-exist in your project alongside the pushio_config_debug.json file you previously added for development.
Lastly, make sure you have created a push-enabled distribution provisioning profile for your application and that your Xcode project is properly Code Signed for Distribution
Now that you have completed the basic configuration and have tested push notifications, we recommend that you continue to the following topics: