Using the iOS SDK

Using the iOS SDK

As part of our integration efforts with our partners, data4life provides SDKs for the following platforms:

  • iOS (Swift)

  • Android (Java)

  • Web (JavaScript)

The data4life SDKs encapsulate different aspects of communication with the backend servers of the data4life Personal Health Data Platform. The SDKs let integration partners store sensitive health data on our secure platform. The SDKs also enable sharing the data with authorized parties and other applications in an easy and secure way.

Updating and validating versions

Data4Life can deprecate or unsupport old SDK versions that aren’t anymore secure or stay occassioning bugs. In that case the user will get notifications from the SDK:

  • If the current version is deprecated, the user will get a notification in the console asking to update to a more recent version from the SDK. The SDK will still be able to be runned and used.

  • If the current version is unsupported, the user will get an error by using the SDK and will need to update to a new version in order to continue using the SDK.

  • If for some reason the version validation can’t happen, the user will get a notification in the console warning that the current version validation is unknown. The SDK will still work, but it might crash.

Software requirements

The iOS SDK has the following software requirements:

  • Xcode 12.5 or later

  • iOS 13.0 or later

  • Swift 5.3 or later

Installing dependency managers

This section describes how you get the SDK up and running. Use the following for dependency management for the iOS SDK:

  • Swift Package Manager is a dependency manager from Apple included in XCode. It builds your dependencies and provides you with binary frameworks while you retain control over your project structure and setup.

Swift Package Manager

To install with Swift package manager, select your project’s Swift Packages tab, and add our repository url, either as ssh or https url:

https://github.com/d4l-data4life/d4l-sdk-ios.git
OR
git@github.com:d4l-data4life/d4l-sdk-ios.git

In the next step, select the latest version, and then import the Data4LifeSDK libraries in your target.

Dependencies of the SDK

The iOS SDK has the following dependencies:

  • Alamofire – HTTP networking library written in Swift

  • AppAuth – iOS and macOS SDK for communicating with OAuth 2.0 and OpenID Connect providers

  • Data4LifeFHIR – data4life minimal FHIR standard models and data types for iOS

  • Data4LifeSDKUtils – data4life Set of private utils used in data4Life Frameworks

  • Data4LifeCrypto – data4life Set of private utils used in data4Life Frameworks

Setting up the SDK

To set up the iOS SDK, follow these steps:

  1. Configure the client information

  2. Handle the OAuth 2.0 redirect URL

  3. Display the login screen

This section describes the steps in more detail.

  1. Prepare the SDK for use by configuring the client information. This must be the first SDK call or the client crashes.

    import UIKit
import Data4LifeSDK

@UIApplicationMain
class AppDelegate: UIResponder, UIApplicationDelegate {

  var window: UIWindow?

  func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey : Any]? = nil) -> Bool {

    let clientId = "client-id#ios"
    let secret = "secret"
    let redirectURLString = "app://oauth"
    let environment = .staging
    Data4LifeClient.configureWith(clientId: clientId,
                                  clientSecret: secret,
                                  redirectURLString: redirectURLString,
                                  environment: environment)

    return true
  }
}

  2. Handle the OAuth 2.0 redirect URL in the AppDelegate class.

    import UIKit
import Data4LifeSDK

@UIApplicationMain
class AppDelegate: UIResponder, UIApplicationDelegate {

  var window: UIWindow?

  func application(_ app: UIApplication, open url: URL, options: [UIApplicationOpenURLOptionsKey : Any] = [:]) -> Bool {

    Data4LifeClient.default.handle(url: url)

    return true
  }
}

  3. Display the login screen. Afterwards, you can use it throughout the app with the default client by providing a view controller to present.

    let viewController = UIApplication.shared.keyWindow?.rootViewController
Data4LifeClient.default.presentLogin(on: viewController, animated: true) { result in
    switch result {
    case .success:
        // Handle success
    case .failure(let error):
        // Handle error
    }
}

  4. Optional: To use the SDK inside extensions, provide the keychainGroupId identifier when you configure the SDK and enable the KeychainSharing capability in the Xcode project. The SDK also requires the AppGroups capability with the same setup.

    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey : Any]? = nil) -> Bool {

    let clientId = "client-id#ios"
    let secret = "secret"
    let redirectURLString = "app://oauth"
    let environment = .staging
    let teamId = "TEAMDID"
    let groupId = "Group1"
    let keychainGroupId = "\(teamId).\(groupId)"
    let appGroupId= "group.unique.id"

    Data4LifeClient.configureWith(clientId: clientId,
                              clientSecret: secret,
                              redirectURLString: redirectURLString,
                              environment: .staging,
                              keychainGroupId: keychainGroupId,
                              appGroupId: appGroupId,
                              environment: environment)

    return true
  }