Adding the MobileFirst Foundation SDK to iOS Applications

improve this page | report issue

Overview

The MobileFirst Foundation SDK consists of a collection of pods that are available through CocoaPods and which you can add to your Xcode project.
The pods correspond to core functions and other functions:

  • IBMMobileFirstPlatformFoundation - Implements client-to-server connectivity, handles authentication and security aspects, resource requests, and other required core functions.
  • IBMMobileFirstPlatformFoundationJSONStore - Contains the JSONStore framework. For more information, review the JSONStore for iOS tutorial.
  • IBMMobileFirstPlatformFoundationPush - Contains the push notification framework. For more information, review the Notifications tutorials.
  • IBMMobileFirstPlatformFoundationWatchOS - Contains support for Apple WatchOS.

In this tutorial you learn how to add the MobileFirst Native SDK by using CocoaPods to a new or existing iOS application. You also learn how to configure the MobileFirst Server to recognize the application.

Prerequisites:

Note: Keychain Sharing capability is mandatory while running iOS apps on simulators using XCode 8.

Jump to:

Adding the MobileFirst Native SDK

Follow the instructions below to add the Mobile Foundation Native SDK to a new or existing Xcode project, and to register the application to the MobileFirst Server.

Before you start, make sure that the MobileFirst Server is running.
If using a locally installed server: From a Command-line window, navigate to the server’s folder and run the command: ./run.sh.

Creating an application

Create an Xcode project or use an existing one (Swift or Objective-C).

Adding the SDK

  1. The Mobile Foundation Native SDK is provided via CocoaPods.
    • If CocoaPods is already installed in your development environment, skip to step 2.
    • If CocoaPods is not installed, install it as follows:
      • Open a Command-line window and navigate to the root of the Xcode project.
      • Run the command: sudo gem install cocoapods followed by pod setup. Note: These commands might take several minutes to complete.
  2. Run the command: pod init. This creates a Podfile.
  3. Using your favorite code editor, open the Podfile.
    • Comment out or delete the contents of the file.
    • Add the following lines and save the changes:

      use_frameworks!
      
      platform :ios, 8.0
      target "Xcode-project-target" do
          pod 'IBMMobileFirstPlatformFoundation'
      end
      
      • Replace Xcode-project-target with the name of your Xcode project’s target.
  4. Back in the command-line window, run the commands: pod install, followed by pod update. These command add the Mobile Foundation Native SDK files, add the mfpclient.plist file, and generate a Pod project.
    Note: The commands might take several minutes to complete.

    Important: From here on, use the [ProjectName].xcworkspace file in order to open the project in Xcode. Do not use the [ProjectName].xcodeproj file. A CocoaPods-based project is managed as a workspace containing the application (the executable) and the library (all project dependencies that are pulled by the CocoaPods manager).

Manually adding the MobileFirst Native SDK

You can also manually add the Mobile Foundation SDK:

To manually add the Mobile Foundation SDK, first download the SDK .zip file from the MobileFirst Operations Console → Download Center → SDKs tab.

  • In your Xcode project, add the Mobile Foundation framework files to your project.
    • Select the project root icon in the project explorer.
    • Select File → Add Files and navigate to the folder that contains the framework files previously downloaded.
    • Click the Options button.
    • Select Copy items if needed and Create groups for any added folders.
      Note: If you do not select the Copy items if needed option, the framework files are not copied but are linked from their original location.
    • Select the main project (first option) and select the app target.
    • In the General tab, remove any frameworks that would get added automatically to Linked Frameworks and Libraries.
    • Required: In Embedded Binaries, add the following frameworks:
      • IBMMobileFirstPlatformFoundation.framework
      • IBMMobileFirstPlatformFoundationOpenSSLUtils.framework
      • IBMMobileFirstPlatformFoundationWatchOS.framework
      • Localizations.bundle
      Performing this step will automatically add these frameworks to Linked Frameworks and Libraries.
    • In Linked Frameworks and Libraries, add the following frameworks:
      • IBMMobileFirstPlatformFoundationJSONStore.framework
      • sqlcipher.framework
      • openssl.framework
    • Note: These steps copy the relevant Mobile Foundation frameworks to your project and link them within the Link Binary with Libraries list in the Build Phases tab. If you link the files to their original location (without choosing the Copy items if needed option as described previously), you need to set the Framework Search Paths as described below.
  • The frameworks added in Step 1, would be automatically added to the Link Binary with Libraries section, in the Build Phases tab.
  • Optional: If you did not copy the framework files into your project as described previously , perform the following steps by using the Copy items if needed option, in the Build Phases tab.
    • Open the Build Settings page.
    • Find the Search Paths section.
    • Add the path of the folder that contains the frameworks to the Framework Search Paths folder.
  • In the Deployment section of the Build Settings tab, select a value for the iOS Deployment Target field that is greater than or equal to 8.0.
  • Optional: From Xcode 7, bitcode is set as the default. For limitations and requirements see Working with bitcode in iOS apps. To disable bitcode:
    • Open the Build Options section.
    • Set Enable Bitcode to No.
  • Beginning with Xcode 7, TLS must be enforced. See Enforcing TLS-secure connections in iOS apps.

Registering the application

  1. Open a Command-line window and navigate to the root of the Xcode project.

  2. Run the command:

     mfpdev app register
    

    You are asked to provide the application’s BundleID. Important: The BundleID is case sensitive.

The mfpdev app register CLI command first connects to the MobileFirst Server to register the application, then generates the mfpclient.plist file at the root of the Xcode project, and adds to it the metadata that identifies the MobileFirst Server.

Tip: You can also register applications from the MobileFirst Operations Console:

  1. Load the MobileFirst Operations Console.
  2. Click the New button next to Applications to register a new application and follow the on-screen instructions.
  3. After the application is registered, navigate to the application’s Configuration Files tab and copy or download the mfpclient.plist file. Follow the onscreen instructions to add the file to your project.

Completing the setup process

In Xcode, right-click the project entry, click on Add Files To [ProjectName] and select the mfpclient.plist file, located at the root of the Xcode project.

Referencing the SDK

Whenever you want to use the Mobile Foundation Native SDK, make sure that you import the Mobile Foundation framework:

Objective-C:

#import <IBMMobileFirstPlatformFoundation/IBMMobileFirstPlatformFoundation.h>

Swift:

import IBMMobileFirstPlatformFoundation


Note about iOS 9 and above:

Starting Xcode 7, Application Transport Security (ATS) is enabled by default. In order to run apps during development, you can disable ATS (read more).

  1. In Xcode, right-click the [project]/info.plist file → Open As → Source Code
  2. Paste the following:
     <key>NSAppTransportSecurity</key>
     <dict>
           <key>NSAllowsArbitraryLoads</key>
           <true/>
     </dict>

Adding Support for Apple watchOS

If you are developing for Apple watchOS 2 and later, the Podfile must contain sections corresponding to the main app and the watchOS extension. See below example for watchOS 2:

# Replace with the name of your watchOS application
xcodeproj 'MyWatchApp'

use_frameworks!

#use the name of the iOS target
target :MyWatchApp do
    platform :ios, 9.0
    pod 'IBMMobileFirstPlatformFoundation'
    end

#use the name of the watch extension target
target :MyWatchApp WatchKit Extension do
    platform :watchos, 2.0
    pod 'IBMMobileFirstPlatformFoundation'
end

Verify that the Xcode project is closed and run the pod install command.

Updating the MobileFirst Native SDK

To update the Mobile Foundation Native SDK with the latest release, run the following command from the root folder of the Xcode project in a Command-line window:

pod update

SDK releases can be found in the SDK’s CocoaPods repository.

Generated MobileFirst Native SDK artifacts

mfpclient.plist

Located at the root of the project, this file defines the client-side properties used for registering your iOS app on the MobileFirst Server.

Property Description Example values
wlServerProtocol The communication protocol with the MobileFirst Server. http or https
wlServerHost The host name of the MobileFirst Server. 192.168.1.63
wlServerPort The port of the MobileFirst Server. 9080
wlServerContext The context root path of the application on the MobileFirst Server. /mfp/
languagePreferences Sets the default language for client sdk system messages. en

Bitcode and TLS 1.2

For information about support for Bitcode and TLS 1.2 see the Additional Information page.

Tutorials to follow next

With the Mobile Foundation Native SDK now integrated, you can now:

Last modified on January 25, 2017