Adding the MobileFirst Foundation SDK to iOS Applications
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.
- Xcode and MobileFirst CLI installed on the developer workstation.
- A local or remote instance of MobileFirst Server is running.
- Read the Setting up your MobileFirst development environment and Setting up your iOS development environment tutorials.
Note: Keychain Sharing capability is mandatory while running iOS apps on simulators using XCode 8.
- Adding the MobileFirst Native SDK
- Manually Adding the MobileFirst Native SDK
- Adding Support for Apple watchOS
- Updating the MobileFirst Native SDK
- Generated MobileFirst Native SDK artifacts
- Bitcode and TLS 1.2
- Tutorials to follow next
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:
Creating an application
Create an Xcode project or use an existing one (Swift or Objective-C).
Adding the SDK
- 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 cocoapodsfollowed by
pod setup. Note: These commands might take several minutes to complete.
- Run the command:
pod init. This creates a
- Using your favorite code editor, open the
- 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.
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].xcworkspacefile in order to open the project in Xcode. Do not use the
[ProjectName].xcodeprojfile. 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:
- In Linked Frameworks and Libraries, add the following frameworks:
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
Open a Command-line window and navigate to the root of the Xcode project.
Run the command:
mfpdev app register
- If a remote server is used, use the command
mfpdev server addto add it.
You are asked to provide the application’s BundleID. Important: The BundleID is case sensitive.
- If a remote server is used, use the command
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:
- Load the MobileFirst Operations Console.
- Click the New button next to Applications to register a new application and follow the on-screen instructions.
- 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:
Note about iOS 9 and above:
- In Xcode, right-click the [project]/info.plist file → Open As → Source Code
- 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:
SDK releases can be found in the SDK’s CocoaPods repository.
Generated MobileFirst Native SDK artifacts
Located at the root of the project, this file defines the client-side properties used for registering your iOS app on the MobileFirst Server.
|protocol||The communication protocol with the MobileFirst Server.||http or https|
|host||The host name of the MobileFirst Server.||192.168.1.63|
|port||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:
- Review the Using the Mobile Foundation SDK tutorials
- Review the Adapters development tutorials
- Review the Authentication and security tutorials
- Review the Notifications tutorials
- Review All Tutorials
Inclusive terminology note: The Mobile First Platform team is making changes to support the IBM® initiative to replace racially biased and other discriminatory language in our code and content with more inclusive language. While IBM values the use of inclusive language, terms that are outside of IBM's direct influence are sometimes required for the sake of maintaining user understanding. As other industry leaders join IBM in embracing the use of inclusive language, IBM will continue to update the documentation to reflect those changes.