Adding the Persistent Mobile Foundation SDK to iOS Applications

Overview

The Persistent Mobile Foundation SDK consists of a collection of frameworks that you can add to your Xcode project.
The frameworks correspond to core functions and other functions:

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

In this tutorial you learn how to add the Persistent Mobile Foundation Native SDK by using manual integration to a new or existing iOS application. You also learn how to configure the PMF to recognize the application.

Prerequisites:

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

Jump to:

Adding the PMF Native SDK

Follow the instructions below to add the PMF Native SDK to a new or existing Xcode project, and to register the application to the PMF.

Before you start, make sure that the PMF 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 PMF Native SDK

You can add the PMF SDK by following below instructions

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

  • In your Xcode project, add the PMF 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:
      • PMFBase.framework
      • PMFOpenSSLUtils.framework
      • PMFWatchOS.framework
      Performing this step will automatically add these frameworks to Linked Frameworks and Libraries.
    • In Linked Frameworks and Libraries, add the following frameworks:
      • PMFJSONStore.framework
      • sqlcipher.framework
      • openssl.framework
      • Localizations.bundle
      • Note: These steps copy the relevant PMF 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 9.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:

     pmfdev app register

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

The pmfdev app register CLI command first connects to the PMF 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 PMF.

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

  1. Load the PMF 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 PMF Native SDK, make sure that you import the PMF framework:

Objective-C:

#import <IBMMobileFirstPlatformFoundation/IBMMobileFirstPlatformFoundation.h>

Swift:

import IBMMobileFoundationSwift


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

You can add PMFWatchOS.xcframework with same manual procedure applicable for other frameworks or You can just drag and drop .xcframework for applicable target under

Target – General – Frameworks, Libraries, and Embedded Contents Section of Xcode

Updating the PMF Native SDK

To use latest available frameworks/xcframeworks just replace the old frameworks/xcframeworks with latest one under Target – General – Frameworks, Libraries, and Embedded Contents Section of Xcode

Same manual addition method applicable here also for SDK support add. (Applicable Target membership can be updated by selecting specific Framework under navigator panel and File Inspector panel checkbox.)

Generated PMF 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 PMF.

Property Description Example values
protocol The communication protocol with the PMF. http or https
host The host name of the PMF. 192.168.1.63
port The port of the PMF. 9080
wlServerContext The context root path of the application on the PMF. /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 PMF Native SDK now integrated, you can now:

▲
Last modified on