This topic provides detailed instructions for integrating your iOS mobile app with Oracle Responsys Mobile App Platform Cloud Service. Follow the steps in this section if you are new to Oracle Responsys Mobile App Platform Cloud Service and you are adding the SDK to your mobile app project for the first time.
Before You Continue
If you have already integrated the Oracle Responsys Mobile App Platform 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.
SDK Support Policy
The Oracle SDK Support Policy for the Oracle Responsys Mobile App Platform Cloud Service SDK / Responsys Push SDK covers only the four most recent Major SDK Releases. For example, if the most current SDK is 6.43.2, the SDK Support Policy covers SDK Versions 6.43.x, 6.42.x, 6.41.x, and 6.40.x.
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 Responsys Mobile App Platform 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 Responsys Mobile App Platform Cloud Service SDK in mobile apps. We strongly recommend not using other vendors' SDKs in the same mobile app as the Oracle Responsys Mobile App Platform 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 Responsys Mobile App Platform 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.
From the Mobile App Developer Console, locate your app and click Edit App.
From your app's page, click Platform.
On the Platform page, click the Add Platform button.
On the Add platform dialog, select iOS Development, and then click Ok.
The iOS Development dialog is displayed. It assumes that you have a .PEM file ready to upload. If you do not, proceed to step [1.2]. If you do, skip to step [1.3]
[1.2] The next step involves creating an Authentication file. Responsys supports Authentication Key Files and Push SSL Certificates (known as a .PEM file) via Apple’s iOS Provisioning Portal. These Authentication files give us permission to speak to Apple’s servers, which ultimately communicate with your application. If you are using .PEM files, 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 yet.
This process can be a bit tricky, so we’ve created guides dedicated solely to generating the necessary files:
[1.3] Once you have generated the Authentication file, head back to the Mobile App Development Console to upload the file.
[1.3.a] On the iOS Development dialog, enter the app title (unique for your app and platform), and then click the Upload button.
[1.3.b] Browse to the location on your computer where the .PEM file is located, select it, and finish the upload.
[1.3.c] Click the Add button to complete the setup.
When completed, it should look like this:
[1.4] Next, download our iOS PushIOManager and a configuration file called pushio_config_debug.json. Click the Downloads menu of the iOS Development row to download these 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.
[2.3] Drag and drop the PushIOManager framework folder into your project.
[2.4] Select Copy items if needed and specify the options to add the files into your project. Click Finish.
Step 3: Add Frameworks
[3.1] Navigate to your project in the Project Navigator, and then navigate to your application target.
[3.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 the frameworks your app will require. Some examples include WebKit.framework, UserNotifications.framework, libsqlite3.0.tbd, and CoreLocation.framework.
Step 4: Adding Linker Flags
[4.1] Click Build Settings.
[4.2] Double-click Other Linker Flags.
[4.4] Enter -ObjC -all_load.
[4.5] The linker switch was added for the Debug and Release versions.
Step 5: 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
[6.2] In your AppDelegate.m file , add the following lines mentioned in below steps in the -(BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions method.
This step is required to configure the SDK. There are several configuration APIs available in SDK, but we recommend to call configureWithFileName: API. Provide the filename of config.json file downloaded in step [1.4]. Please make sure your config.json files are in the app bundle.
[6.5] Registering your app with APNS and Responsys server:
There are several APIs in SDK to register the App with APNS. We will use registerForAllRemoteNotificationTypes which will ask for alert, badge and sound permissions from user. This API will display system prompt for push notification permission. Call this API on completion of configureWithFileName API.
After registerForAllRemoteNotificationTypes completion we will call registerApp API. This api is responsible for syncing the sdk configurations and push permissions to Responsys servers.
Choose All Active Devices from the Audience dropdown menu.
Type in a message and click Send Now.
If all went well, you should see your first true iOS push notification!
[6.9] Add the User Identifier methods
Responsys uses the USER_IDENTIFIER parameter to uniquely identify "known users" of your app. You must add the appropriate user identifier methods to register a user when the user logs in to the mobile app, to unregister a user when the user logs out, and you can also retrieve the known user's ID.
[6.9.1] Add code for "known user" identification.
Responsys uses the USER_IDENTIFIER parameter to uniquely identify "known users" of your app. To do this, when the user signs in or signs up in the app, you need to call the register user ID function of the SDK (where <match_key_value> is the value of the match key field):
Coordinate with the Responsys Account Admin regarding which match key field to use; the match key field must be chosen when the Account Admin creates the app channel list and it cannot be changed later. For more information about the match key, and recommendations for choosing which Profile List field to use as the match key, see the "Setting up the App Channel List" topic in the Mobile App Channel Configuration Guide.
Example of how "known user" identification works
In the following example, the match key field is CUSTOMER_ID, and let's assume that the CUSTOMER_ID values are normalized on all systems involved (that is, leading and trailing spaces are removed).
1) A customer named John Doe with a customer ID of A1B2C3D4 logs in to your app:
2) Next, the backend server authenticates the user, and sends the mobile app the user's customer ID in the form of a string:
Successful Login to backend server > the customer ID A1B2C3D4 is obtained
3) Finally, the app registers the user with Push SDK registerUserID method:
When the user finishes the session and logs out, the app unregisters the user by calling registerUserID and passing nil as the argument. (This action has the effect of clearing the USER_IDENTIFIER_ field in the App Channel List.)
iOS 12 apps can implement provisional authorization along with other notification options.
Apps requesting provisional authorization do not need to prompt the user for push permission. Notifications can be "delivered quietly" which does not require user permission initially. When a notification is delivered quietly, it can only be seen in the iOS Notification Center. The notification will not display as a banner, make a sound, and so on. Later on, the user will need to explicitly select whether they want to keep receiving messages "prominently" or "quietly". They also can turn off these notification from the iOS Notification Center, so that only relevant messages are delivered.
To implement this you need to pass UNAuthorizationOptionProvisional while registering.
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, don't call registerForAllRemoteNotificationTypes which is responsible for showing for system prompt for push notification permission. You can delay this api call and call whenever you want
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 configurations, it's time to prepare your app for the additional capabilities available when you use Oracle Responsys to send your push and in-app messaging campaigns. We recommend that you continue to the following topics: