Chapter 3. Native iOS (Swift)

3.1. Download

Warning

If you encounter this problem, refer to the Red Hat Knowledge Base article Swift-based iOS application crashes upon startup when signed using an enterprise distribution certificate without Organisational Unit field for detailed instructions on how to resolve the problem.

3.1.1. CocoaPods

Note

CocoaPods is available only on OSX.

CocoaPods is a Swift And Objective-C dependency manager for Xcode projects. It is built with Ruby, which comes pre-installed with OSX. It is used to distribute the RHMAP iOS Swift and iOS Objective-C Client SDKs.

3.1.1.1. Install CocoaPods Using RubyGems

To install CocoaPods using the RubyGems package manager, execute the following command. This requires the sudo command to be enabled in OSX. 

sudo gem install cocoapods

As an optional part of the CocoaPods setup, you can store your Podspec metadata locally at ~/.cocoapods/repos. This helps to increase the dependency resolution speed and shortens the build time for your apps. To clone the spec-repo and create the directory, execute the following command: 

pod setup

3.1.1.2. Install CocoaPods Without Using sudo.

Alternatively, to install CocoaPods without using sudo, follow the Sudo-less Installation section of the CocoaPods Getting Started Guide.

3.1.1.3. Install the Required Plugins

The RHMAP iOS Objective-C and Swift SDK packages rely on the cocoapods-packager and cocapods-appledoc plugins. To install both plugins, execute the following command: 

[sudo] gem install cocoapods-packager cocoapods-appledoc

3.1.1.4. Enable CocoaPods in an Xcode Project

To enable Cocoapods Xcode app project after installation execute the following commands:

  1. To navigate to the folder of your Xcode project, use: 

    cd <project_directory>

  2. To create a podfile (if it does not already exist) in your project folder and automatically populate it with targets specified within the project, execute the following command: 

    pod init

3.1.1.5. Install Dependencies Using CocoaPods

To install the dependencies defined in the podfile of Xcode project using CocoaPods, execute the following command: 

pod install

3.2. Get Started

This SDK lets you use RHMAP APIs in Swift apps for iOS version 8 or higher.

The RHMAP iOS Swift SDK is an open-source project hosted in the FeedHenry iOS SDK repository on Github. Feel free to fork it and make a contribution to this project.

Before using this SDK:

3.2.1. New App

Clone the sample app to get started with a new iOS application which has the RHMAP iOS Swift SDK included as a CocoaPods dependency. 

git clone https://github.com/feedhenry-templates/blank-ios-swift.git
cd blank-ios-app

Fetch the dependencies defined in the Podfile: 

pod install

Open the blank-ios-app.xcworkspace workspace in Xcode. The required dependencies are located in the Pods group.

3.2.2. Existing App

If your app does not have a Podfile already, create a new file named Podfile at the root of your project with the following contents: 

source 'https://github.com/CocoaPods/Specs.git'

project 'ProjectName.xcodeproj'
platform :ios, '8.0'
use_frameworks!

target 'TargetName' do
    pod 'FeedHenry', '4.1.1'

end

Replace '4.1.1' with the version of RHMAP iOS Swift SDK you are targeting, ProjectName.xcodeproj with the name of your project and TargetName with the name of your target. If you do not specify a version number, the latest version in the CocoaPods central repository will be used.

Fetch the dependencies defined in the Podfile: 

pod install

You can now open ProjectName.xcworkspace in Xcode.

3.2.3. Setup

You must define the properties which allow your app to communicate with RHMAP servers. Add the following values to the fhconfig.plist configuration file: 

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>host</key>
  <string>__RHMAP_Core_host__</string>
  <key>appid</key>
  <string>__Client_App_ID__</string>
  <key>projectid</key>
  <string>__Project_ID__</string>
  <key>appkey</key>
  <string>__Client_App_ API_key___</string>
  <key>connectiontag</key>
  <string>__Connection_tag__</string>
</dict>
</plist>

See Projects - Connections for more information on connections between Client Apps and Cloud Apps.

3.2.4. Initialization

Before invoking any cloud requests from the RHMAP iOS Swift SDK, you must first initialize it. Copy the following code snippet to your App Delegate’s application(_, didFinishLaunchingWithOptions:) method, or any other location which ensures the code is called before any cloud requests: 

import FeedHenry

func application(application: UIApplication, didFinishLaunchingWithOptions launchOptions: [NSObject: AnyObject]?) -> Bool {
  FH.init { (resp:Response, error: NSError?) -> Void in
    if let error = error {
      print("Error: \(error)")
      return
    }
    print("Response: \(resp.parsedResponse)")
  }
  return true
}

3.3. API Documentation

See the API Docs - documentation for all Client APIs

3.4. Swift 2.3 and Swift 3

This release of RHMAP includes Swift 2.3 and Swift 3.0 functionality. Using Swift 2.3 or Swift 3.0 allows you to use Xcode 8.x and iOS 10 specific features, such as iMessage app extensions. The following templates are available:

3.4.1. Migrating Apps to Swift 2.3

To migrate your app to Swift 2.3:

  1. Review the Swift migration guide.
  2. Make sure your code is working before migrating.

  3. Change the Podfile contents to the following: 

        pod 'FeedHenry', '4.2.1'

  4. Install the pod: 

        pod install
  5. Open the Xcode 8.x workspace by double clicking on the ProjectName.xcworkspace.
  6. When prompted to migrate the code, choose Swift 2.3.
  7. Build your app locally and validate that everything is working.

3.4.2. Migrating Apps to Swift 3.0

To migrate your app to Swift 3.0:

  1. Review the Swift migration guide. Note the following Swift 3 coding style changes:

    • Name functions and methods according to their side-effects.

      • Those without side-effects should read as noun phrases, for example, x.distance(to: y), i.successor().
      • Those with side-effects should read as imperative verb phrases, for example, print(x), x.sort(), x.append(y).
    • Names of types and protocols are UpperCamelCase.
    • Everything else is lowerCamelCase.
  2. Make sure your code is working before migrating.

  3. Change the Podfile contents to the following: 

        pod 'FeedHenry', '5.0.3'

  4. Install the pod: 

        pod install
  5. Open the Xcode 8.x workspace by double clicking on the ProjectName.xcworkspace.

  6. When prompted to migrate the code, choose Swift 3. Note the following:

    • It is unlikely that the app code will compile first time. Fix your code until it passes all unit tests.

    • Be aware of the following:

      • sort() on Array is now a mutable function
      • the difference between Any and AnyObject
      • the difference between Data and NSData
    • Consider your API label names using the Swift Api Design Guidelines.
  7. Build your app locally and validate that everything is working.