For up-to-date product documentation, see the IBM MobileFirst Foundation Developer Center.

Migrate an existing native iOS projects to version V8.0.0 with CocoaPods

Migrate your existing native iOS project to work with V8.0.0 by getting the IBM MobileFirstâ„¢ Platform Foundation iOS SDK using CocoaPods and making changes in the project configuration.

Before you begin

Note: MobileFirst development is supported in Xcode from version 7.1 by using iOS 8.0 and later. You must have:


The SDK contains required and optional SDKs. Each required or optional SDK has its own pod.

The required IBMMobileFirstPlatformFoundation pod is the core of the system. It implements client-to-server connections, handles security, analytics, and application management. The following optional pods provide additional features.

Table 1. Pods for installing optional frameworks
Pod Feature
IBMMobileFirstPlatformFoundationPush Adds the IBMMobileFirstPlatformFoundationPush framework for enabling Push. For more information, see Push notification.
IBMMobileFirstPlatformFoundationJSONStore Implements the JSONStore feature. Include this pod in your Podfile if you intend to use the JSONStore feature in your app. See JSONStore.">JSONStore.
IBMMobileFirstPlatformFoundationOpenSSLUtils Contains the MobileFirst embedded OpenSSL feature and loads automatically the openssl framework. Include this pod in your Podfile if you intend to use the OpenSSL provided by MobileFirst. For more information on OpenSSL options, see Enabling OpenSSL for iOS.


  1. Open your project in Xcode.
  2. Delete the WorklightAPI folder from your Xcode project (move it to trash).
  3. Modify your existing code in the following ways:
    1. Remove $(SRCROOT)/WorklightAPI/include from the header search path.
    2. Remove $(PROJECTDIR)/WorklightAPI/frameworks from the frameworks search path.
    3. Remove any references to the static librarylibWorklightStaticLibProjectNative.a.
  4. In the Build Phases tab, remove the links to the following frameworks and libraries (these are re-added automatically by CocoaPods):

    • libWorklightStaticLibProjectNative.a
    • SystemConfiguration.framework
    • MobileCoreServices.framework
    • CoreData.framework
    • CoreLocation.framework
    • Security.framework
    • sqlcipher.framework
    • libstdc++.6.dylib
    • libz.dylib
  5. Close Xcode.
  6. Get the IBM MobileFirst Platform Foundation iOS SDK from CocoaPods. To get the SDK, complete the following steps:
    1. Open Terminal at the location of your new Xcode project.
    2. Run the pod init command to create a Podfile file.
    3. Open the Podfile file that is in the root of the project with a text editor.
    4. Comment out or remove the existing content.
    5. Add the following lines and save the changes, including the iOS version:

      use_frameworks! platform :ios, 9.0 pod 'IBMMobileFirstPlatformFoundation'

    6. Specify additional pods in the file from the list above, if your app needs to use the additional functionality that they provide. For example, if your app uses OpenSSL, the Podfile might look like this:

      use_frameworks! platform :ios, 9.0 pod 'IBMMobileFirstPlatformFoundation' pod 'IBMMobileFirstPlatformFoundationOpenSSLUtils'

      For a list of optional pods, see Pods for installing optional frameworks.


      The previous syntax imports the latest version of the IBMMobileFirstPlatformFoundation pod. If you are not using the latest version of MobileFirst, you need to add the full version number, including the major, minor, and patch numbers. The patch number is in the format YYYYMMDDHH. For example, for importing the specific patch version 8.0.2016021411 of the IBMMobileFirstPlatformFoundation pod the line would look like this:

      pod 'IBMMobileFirstPlatformFoundation', '8.0.2016021411' Or to get the last patch for the minor version number the syntax such is

      pod 'IBMMobileFirstPlatformFoundation', '~>8.0.0'

    7. Verify that the Xcode project is closed.
    8. Run the pod install command.

      This command installs the MobileFirst SDK IBMMobileFirstPlatformFoundation.framework and any other frameworks that are specified in the Podfile and their dependencies. It then generates the pods project, and integrates the client project with the MobileFirst SDK.

  7. Open your ProjectName.xcworkspace file in Xcode by typing open ProjectName.xcworkspace from a command line. This file is in the same directory as the ProjectName.xcodeproj file.
  8. Replace all of the existing MobileFirst imports of headers with a single entry of the following new umbrella header:
    • Objective C:

      #import <IBMMobileFirstPlatformFoundation/IBMMobileFirstPlatformFoundation.h>

    • Swift:

      import IBMMobileFirstPlatformFoundation

    If you are using Push or JSONStore, you need to include an independent import.

    • For Objective C:

      #import <IBMMobileFirstPlatformFoundationPush/IBMMobileFirstPlatformFoundationPush.h>

    • For Swift:

      import IBMMobileFirstPlatformFoundationPush


    • For Objective C:

      #import <IBMMobileFirstPlatformFoundationJSONStore/IBMMobileFirstPlatformFoundationJSONStore.h>

    • For Swift:

      import IBMMobileFirstPlatformFoundationJSONStore

  9. In the Build Settings tab, under Other Linker Flags, add $(inherited) at the beginning of the -ObjC flag. For example:

    Figure 1. Adding $(inherited) to ObjC flag in Xcode Build Settings

    Xcode Build Settings tab, showing where to add "$(inherited) in front of "ObjC" flag

  10. Beginning with Xcode 7, TLS must be enforced, see Enforcing TLS-secure connections in iOS apps.


Your application is now upgraded to work with the IBM MobileFirst Platform Foundation, V8.0.0 iOS SDK.

What to do next

Parent topic: Migrating existing native iOS applications