d4l-data4life/d4l-sdk-ios

Pure Swift API client for PHPD that automatically handles encryption

Data4Life Core iOS SDK

Pure Swift API client for PHDP that automatically handles encryption

Explore the docs »

Report Bug · Request Feature

Table Of Contents

• About The Project
• Installation
  • Swift Package Manager
  • Configuration
• Documentation
• Changelog
• Versioning
• Contributing
• Copyright and License

About The Project

Pure Swift API client for PHDP that automatically handles encryption.

Installation

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

[email protected]:d4l-data4life/d4l-sdk-ios.git

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

Configuration

To get started with the 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.

Configure the client information

This step is achieved by calling the configureWith method on didFinishLaunchWithOptions. This must be the first SDK call or the client crashes.

📎	Client Id needs the #ios at the end in case it’s missing, and the redirect URL string looks like domain.com.client-id without the need to have the oauth:// suffix. For the complete settings for your client, refer to your json configuration file provided by us upon request.

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-redirect" // Must look like "domain.com.client-id"
    let environment = .staging // .development / .production
    let platform = .d4l //.s4h
    Data4LifeClient.configureWith(clientId: clientId,
                                  clientSecret: secret,
                                  redirectURLString: redirectURLString,
                                  environment: environment,
                                  platform: platform)

    return true
  }
}

Handle the OAuth 2.0 redirect URL

This step is achieved by calling the handle(url:) method on the main delegate. In case the app has no SceneDelegate set up, it must be added in the open url: method of the AppDelegate.

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
  }
}

If instead of the AppDelegate only, a SceneDelegate is present, the code needs to be handled at the SceneDelegate level, in the openURLContexts method:

import UIKit
import Data4LifeSDK

class SceneDelegate: UIResponder, UIWindowSceneDelegate {

    func scene(_ scene: UIScene, openURLContexts URLContexts: Set<UIOpenURLContext>) {
        guard let url = URLContexts.first?.url else {
            return
        }

        Data4LifeClient.default.handle(url: url)
    }
}

Last step for handling the login url is to enter the redirect url scheme in the Info tab of the app target setting:

Display the login screen

Login screen can be displayed 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
    }
}

💡	(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-scheme"
    let environment = .staging
    let teamId = "TEAMDID"
    let groupId = "Group1"
    let keychainGroupId = "\(teamId).\(groupId)"
    let appGroupId= "group.unique.id"
    let platform = .d4l

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

    return true
  }

Documentation

Further documentation on how to use it can be found here

Changelog

See changelog

Versioning

We use Semantic Versioning as a guideline for our versioning.

Releases use this format: {major}.{minor}.{patch}

• Breaking changes bump {major} and reset {minor} & {patch}

• Backward compatible changes bump {minor} and reset {patch}

• Bug fixes bump {patch}

Contributing

You want to help or share a proposal? You have a specific problem? Read the following:

• Code of conduct for details on our code of conduct.

• Contributing for details about how to report bugs and propose features.

• Developing for details about our development process and how to build and test the project.

Copyright and License

Copyright (c) 2021 D4L data4life gGmbH / All rights reserved. Please refer to our License for further details.