Rebar iOS Getting Started

Monkton, Inc.

This documentation is intended to be a step by step getting started guide for iOS. You should be able to clone from Github and after adding the Rebar SDK, make minor configuration changes, build the sample project without issue.

Some configuration items aren't necessary if you are downloading directly from Github, others will be necessary if you are adding Rebar to an already existing project.

At present our documentation only covers Swift for code level examples.

Rebar iOS Frameworks

Rebar is composed of two frameworks, Rebar.framework and RebarSupport.framework.

Rebar.framework is a Swift framework that has a majority of the user interface and business logic. Our releases will keep this framework on the latest version of Swift.

Note At this time for XCode, Swift frameworks must be on the same version of Swift. Rebar is currently on Swift 5.

RebarSupport.framework is an Objective-C framework that combines some user interface logic, some business logic, and low level implementation code of many security features.

Both libraries are necessary for any project to work and inherit Rebar's security and compliance features.

Example folder structure for an app

Note Monkton strongly encourages all app development to be done in Swift.

Framework Deployment

The Rebar SDK is deployed within your project directory. We strongly suggest creating a project folder called rebar-sdk within the root of your project. Place the rebar-sdk.zip file containing the Rebar SDK in the rebar-sdk folder. From there, you will unzip the directory. You should have a Production and Development folder within your rebar-sdk folder now.

Be sure to add to your .git-ignore file the paths: rebar-sdk/Production and rebar-sdk/Development—this will prevent the unpacked binaries from being stored in your repository during checkin.

You will want to ensure that, when you include this CI/CD pipeline into your project, you unzip the rebar-sdk.zip file before building.

The Rebar frameworks are "fat binaries" meaning they include "slices" of each applicable system they run on. The "Development" frameworks include the x86_64 simulator builds along with the arm64 slice. The "Production" builds include only the arm64 slice for devices. This is for App Store approval in addition to reducing the size of the binary. Monkton strongly urges you to include the "Strip Simulators" script as the

Note Bitcode is not enabled for our builds at this time.

Note The x86_64 simulator build does not include FIPS 140-2 support.

Note Rebar supports two iOS versions behind. At this time we support iOS 12 and iOS 13.

High Level Integration Checklist

  • Create Rebar SDK Folder

    Within your root project directory, create a folder called rebar-sdk

  • Copy the Rebar SDK

    Within the rebar-sdk folder, copy the latest rebar-sdk.zip which contains the full Rebar SDK

  • Unpack the Rebar SDK

    Unzip the rebar-sdk.zip into the rebar-sdk folder

    • Validate Folders

      You should have a rebar-sdk/Development and rebar-sdk/Production with the Rebar SDK folders

  • Add Folders to .git-ignore

    Ensure that you don't commit unpacked binaries, leading to wasted space. Add the two paths to your ignore file: rebar-sdk/Development and rebar-sdk/Production

  • Update CI/CD Pipeline

    If you are using GitLab, ensure that your CI/CD pipeline includes unpacking the rebar-sdk.zip folder.

Github

Monkton publishes examples under the MIT license on Github. These are free to use as starting templates for your projects.

You can clone the Rebar iOS Sample via the command line (or your favorite GUI util):

git clone https://github.com/monktoninc/rebar-ios-samples.git

Additionally you can download directly as a zip file from Github:

https://github.com/monktoninc/rebar-ios-samples

From there, if the libraries are installed correctly under the Framework Deployment section the project should compile without a single error.

One Touch Setup

In our strive to make developing secure apps easy, you can simply run the ./setup-project.sh file in the project root.

Setup will prompt for:

  • Bundle Identifier: The identifier used within the app
  • Bundle Prefix: The prefix used by the app, also know as the Team Id found in the developer portal
  • API Url: The API Endpoint of your application, eg: https://api.example.com/v1
  • URL Scheme: The URL Scheme for the app to be opened by other apps

After running this script, the bulk of the setup is now done. Developers may need to choose the provisioning profile.

Warning If there is a runtime error for the setup script, permissions may need to be modified with chmod +x setup-project.sh

Bitcode

Bitcode is not enabled for Rebar and can't be for projects using Rebar at this time.

Compiling the Github samples

To be able to run the projects and authenticate, you will need to finish the Entitlements and Configuration Files sections of this guide, but at this point you should be able to compile the sample project without errors.

Embedding Configuration Files

Deploying the app configuration files is the next step. These are the app-config.json files that drive the local configuration for the app. Documentation on these configuration files is located here. These files already exist. You will need to modify them for your project to customize settings.

Structure is as follows:

${PROJECT_DIR}/config/production/app-config.json

${PROJECT_DIR}/config/development/app-config.json

${PROJECT_DIR}/config/test/app-config.json

You will be required to update the rebar-xcode-actions to add any customized config definitions. By default, the script performs the copy actions defined below:

if [ "${CONFIGURATION}" == "Debug" ]; then
cp -r "${PROJECT_DIR}/config/development/app-config.json" "${BUILT_PRODUCTS_DIR}/${PRODUCT_NAME}.app"
fi
if [ "${CONFIGURATION}" == "Test" ]; then
cp -r "${PROJECT_DIR}/config/test/app-config.json" "${BUILT_PRODUCTS_DIR}/${PRODUCT_NAME}.app"
fi
if [ "${CONFIGURATION}" == "Release" ]; then
cp -r "${PROJECT_DIR}/config/production/app-config.json" "${BUILT_PRODUCTS_DIR}/${PRODUCT_NAME}.app"
fi

This script determines which type of build is being run. Once that build is determined, it will copy the appropriate configuration file to the output app folder.

General Rebar Configuration

Entitlements

The entitlements file (RebarApp.entitlements in the Github project) needs to be modified for Keychain Access Groups. Modify the $(AppIdentifierPrefix)YOUR-APP-IDENTIFIER to have the suffix be your bundle id. The 2nd item, $(AppIdentifierPrefix)monktonapps should map to rebar.keychain.group in your app-config.json file.

Note This requires customization

Configuration Files

The configuration files are located under the Config folder within the sample project. You will need to customize these settings, the documentation on these configuration files is located here.

Developing with Rebar

Includes

For Swift, both Rebar and RebarSupport should be included in the necessary files

import Rebar
import RebarSupport

Class Inheritance

App Delegate

The App's app delegate should extend from RebarAppDelegate and implement the configureApp function. Any overridden methods should invoke the superclass implementation.

@UIApplicationMain
class AppDelegate: RebarAppDelegate {

	override func configureApp() {
		// Set the configuration
				RebarAppController.default.setConfiguration(MyAppAppConfiguration());

		// Set the Database configuration
		RebarDatabaseManager.default.register(MyAppDatabase.self);
		
	}

}

Databases

All databases must inherit from RebarDatabase, the root database class. This class manages all security and encryption for the database file. Each database must be registered in the RebarAppDelegate's configureApp method as noted in the App Delegate section above.

Further details on how to configure these classes are located in the Application Databases class documentation.

App Configuration Class

A single configuration should be created that extends from the RebarAppConfiguration class. The configuration must be registered in the RebarAppDelegate's configureApp method as noted in the App Delegate section above.

Further details on how to configure this class are located in the Application Configuration class documentation.

App UI design

Building the App UI is straight forward. Interfaces can be build via code, storyboards, or NIBs. Whatever the development team is comfortable with.

Main UI Screen

The UI of the app being developed should be developed as one normally would, Rebar instantiates, contains, and manages the UI for the entire lifecycle of the App. There is no customization necessary (beyond the mainScreen configuration below) within the UI code to accommodate Rebar.

If the main UI class is a NIB or via code, the app-config.json configuration main-screen can be set. This is the class name of the main UI class. If the development is in Swift, the class must also declare the @objc above the class definition. This is necessary to instantiate the UI.

If the class uses storyboards, within the Application Configuration class class you can define as below:

	// Gets the main app screen
	public override func mainScreen() -> UIViewController? {
		let mainStoryboard: UIStoryboard = UIStoryboard(name: "MyMainViewControllerStoryboard", bundle: NSBundle(forClass: self.dynamicType))
		let setViewController: MyMainViewControllerStoryboard! = mainStoryboard.instantiateViewControllerWithIdentifier("MyMainViewControllerStoryboard") as! MyMainViewControllerStoryboard
		return setViewController;
		
	}

If the interface uses NIBs, the interfaces can be loaded from their NIB automatically within the class files:

class MySettingsViewController : UIViewController {

	required init() {
		super.init(nibName: "MySettingsViewController", bundle: NSBundle(forClass: self.dynamicType));
		
	}

}

welcomeScreen

This method allows for the instantiation of a welcome screen class. This should return the a view controller that allows the user to create an account or login to the app. This can instantiate a UIViewController itself or instantiate and return a storyboard.

This is an optional setting in the app-config.json file if you aren't implementing a storyboard or overriding this method.

To instantiate a storyboard in iOS, see the example below:

	// Gets the main app screen
	public override func welcomeScreen() -> UIViewController? {
		let mainStoryboard: UIStoryboard = UIStoryboard(name: "MyMainViewControllerStoryboard", bundle: NSBundle(forClass: self.dynamicType))
		let setViewController: MyMainViewControllerStoryboard! = mainStoryboard.instantiateViewControllerWithIdentifier("MyMainViewControllerStoryboard") as! MyMainViewControllerStoryboard
		return setViewController;
		
	}

Data at Rest (Storing files and data)

For secure database access, you must inherit from RebarDatabase, please read the App Databases documentation as well as the Data at Rest for more information.

For storing and reading flat files please read the Data at Rest documentation. Rebar implements the RebarFileManager to read and write files securely.

For storing settings, the RebarUserDefaults provides access to securely store settings, this is available in the Data at Rest documentation

Data in Transit (Network calls)

For secure web service calls (HTTPS/TLS) please consult the Data in Transit documentation.

At this time only HTTPS calls are supported. Rebar will support other protocols in the near future.