Adding the Persistent Mobile Foundation SDK to iOS Applications

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

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 following command.

    ./run.sh

Creating an application

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

Adding the PMF Native SDK

  • 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 (Release 9.1) or xcframework (Release 9.2) 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 (Release 9.1) or xcframework (Release 9.2) 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 (Release 9.1) or xcframework (Release 9.2) files are not copied but are linked from their original location.

    • Select the main project (first option) and select the app target.
      Release 9.1

      • 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 automatically adds the frameworks to Linked frameworks and Libraries.

      • In Linked frameworks and Libraries, add the following frameworks:
        • PMFJSONStore.framework
        • sqlcipher.framework
        • openssl.framework
        • Localizations.bundle

      Release 9.2

      • Performing this step automatically add the xcframework to Frameworks, Libraries and Embedded Content of the General Tab. Choose embedding option of xcframework to Embed and Sign.
      • User must need to include below Localization file by selecting Copy items if needed option. Localizations Bundle file will appear in Copy Bundle Resource section of Build Phase Tab:
        Localizations.bundle.
      • Choose Do Not Embed option for SQLCipher.xcframework only, to avoid any hurdles during App-Store upload process.

    • These steps copy the relevant PMF xcframeworks 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.

      See the following table for mapping xcframeworks as per the requirement.

      Functionality Required xcframeworks
      Base - PmfBase.xcframework
      - PmfSwift.xcframework
      JSONStore - All the xcframeworks listed in the Base row
      - PmfJSONStore.xcframework
      - SQLCipher.xcframework
      - PmfOpenSSLUtils.xcframework (If you want to use encryption/decryption of PMF)
      Push - All the xcframeworks listed in the Base row
      - PmfPush.xcframework
      Analytics - All the xcframeworks listed in the Base row
      - PmfAnalytics.xcframework
      LiveUpdate - All the xcframeworks listed in the Base row
      - PmfLiveUpdate.xcframework
  • The frameworks added in the previous step, 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 12.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 and later, 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 following command.

     pmfdev app register

    If a remote server is used, add it by using the following command.

    pmfdev server add

    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: 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.0.2.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