iOS & ResearchKit SDKs

We support iOS development with three frameworks: BridgeSDK, BridgeAppSDK, and CMSSupport, as well as our own forks of Apple's open-source ResearchKit and AppCore frameworks.

The relevant Github repos are:

BridgeSDK
A framework to access the Bridge REST API
BridgeAppSDK
An extensible, customizable application framework for building mHealth apps using Bridge and ResearchKit
CMSSupport
A framework providing support for correctly encrypting files for upload to Bridge
AppCore
Deprecated; use BridgeAppSDK instead. Sage's updated and modified fork of Apple's AppCore framework
ResearchKit
Sage's fork of Apple's ResearchKit framework

BridgeSDK

The BridgeSDK framework is written in Objective-C, and provides robust and secure access to the Bridge REST API for your iOS apps under the BSD license. It supports caching of some Bridge objects (with support for more coming soon), NSURLSession background uploads of data, and accessing much of the REST API via background downloads so your app can continue to work when no Internet connection is available.

BridgeSDK supports Xcode 7 and newer, and has a minimum target version of iOS 8.0.

Adding BridgeSDK directly to your project

BridgeAppSDK (see below) includes BridgeSDK as a sub-project, so if you intend to use that framework, skip these instructions and follow the ones in that section.

Otherwise:

  • Add the BridgeSDK project to the app target for your project.

  • Add the BridgeSDK target's build product (BridgeSDK.framework) to the Linked Frameworks and Libraries and Embedded Frameworks sections on your app target's General tab (or, alternatively, add it to the Link Binary with Libraries and Embed Frameworks build phases).

  • In your AppDelegate source file, import the BridgeSDK:

Objective-C:

@import BridgeSDK;

Swift:

import BridgeSDK
  • From your AppDelegate's application:willFinishLaunchingWithOptions: method, before calling any other BridgeSDK methods, call one of the its setup methods with your study name (provided by Sage when your Bridge study was created), e.g.:

Objective-C:

- (BOOL)application:(UIApplication *)application willFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
    ...
    [BridgeSDK setupWithStudy:@"mystudyname" cacheDaysAhead:4 cacheDaysBehind:1];
    ...
}

Swift:

func application(_ application: UIApplication, willFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool {
        ...
        BridgeSDK.setup(withStudy: "mystudyname", cacheDaysAhead: 4, cacheDaysBehind: 1)
        ...
    }

Using BridgeSDK in your project

BridgeSDK is organized into 'managers' that correspond roughly to the Bridge REST APIs. You can obtain a default instance of an API manager from the component manager (SBBComponentManager) via class methods or, more usually (in Objective-C code at least), via the SBBComponent() convenience macro. For example, to sign up a new participant to your study, you might make a call like this:

Objective-C:

[SBBComponent(SBBAuthManager) signUpWithEmail:email
                                        username:email
                                        password:password
                                    dataGroups:dataGroups
                                    completion:^(NSURLSessionTask * __unused task,
                                                    id __unused responseObject,
                                                    NSError *error)
    {
        dispatch_async(dispatch_get_main_queue(), ^{
            if (!error) {
                // handle successful sign-up, e.g. ask the user to click the link in the verification email before proceeding to sign them in with these credentials
            } else {
                // handle failed sign-up
            }
        });
    }];

Swift:

let authManager = SBBComponentManager.component(SBBAuthManager.self) as! SBBAuthManagerProtocol
authManager.signUp(withEmail: email, username: email, password: password) { (_, responseObject, error) in
    DispatchQueue.main.async {
        guard error == nil else {
            // handle failed sign-up
            return
        }
        // handle successful sign-up, e.g. ask the user to click the link in the verification email before proceeding to sign them in with these credentials
    }
}

See the BridgeSDK documentation for more details, and the BridgeAppSDK framework and sample app source code for working examples.

CMSSupport

The CMSSupport framework was built to provide drop-in CMS encryption support for file uploads to Bridge in apps built with Apple's open-source AppCore framework, or with Sage's extensively modified and updated fork of AppCore.

Apple no longer actively maintains their fork of the AppCore framework, and our fork is now only minimally maintained in support of a handful of legacy applications that still use it. We strongly recommend all new apps should instead be based on the BridgeAppSDK framework and its sample app (see below). BridgeAppSDK also uses the CMSSupport framework, mainly for the OpenSSL framework target it builds.

You would need to use the CMSSupport framework directly only if you are either building an app based on one of the open-source sample apps in ResearchKit on github, which we do not recommend; adding Bridge support to an existing app; or building a Bridge-based mHealth app from scratch without using either AppCore or BridgeAppSDK.

BridgeAppSDK

The BridgeAppSDK framework is written primarily in Swift 3.0, and provides an extensible and customizable application framework for building mHealth apps using Bridge and ResearchKit. It supersedes both Apple's and Sage's forks of the older AppCore framework, which was not built to be extensible or customizable and is therefore no longer being actively supported.

BridgeAppSDK includes the correct commits of BridgeSDK, CMSSupport, and ResearchKit as git submodules, so when you clone it you should do so recursively:

git clone --recursive https://github.com/Sage-Bionetworks/BridgeAppSDK.git

If you've already cloned the repo without the --recursive option, you can do this from within the BridgeAppSDK directory to get the submodules:

git submodule update --init --recursive

The BridgeAppSDK Xcode project includes the BridgeAppSDK target for building the framework, and the BridgeAppSDKSample target for building a sample app demonstrating how to use the framework to build a basic functioning Bridge/ResearchKit mHealth app.