Custom UI Guide

UsherSDK doesn’t provide you with the default UI, but it provides you with UIProtocol for you to conform to so that your own custom UI can plugin to UsherSDK and be called out as needed by workflows.

In order to make your own ui implementation e.g a UIViewController subclass work with UsherSDK, You need to do the following two steps:

  1. Make sure your UIViewController conforms to the corresponding UsherSDK‘s UIProtocol.
  2. Register your UIViewController subclass with UsherSDK by calling corresponding registration functions.

After you register your own classes to UsherSDK, the instance of your class will be used to work with UsherSDK workflows that need to present the user interface.

Example:

Assume that you have a LoginViewController in your app. You can register it in UsherSDK so that UsherSDK can use your LoginViewController to perform login operation.

Conform to UIProtocol

Make sure your LoginViewController conforms to LoginUIProtocol

extension LoginViewController: LoginUIProtocol {

// implementations of functions defined in LoginUIProtocol
// ...
}

UI class registrations

Now your LoginViewController conforms to LoginUIProtocol. We can begin registering your LoginViewController to UsherSDK:

// register LoginUIClass with your own LoginViewController
UsherSDK.registerLoginUIClass(LoginViewController.self)

After finishing two steps above, you own custom UI can work with UsherSDK.

UI Classes

There are many UsherSDK workflows that need to present user interface. You need to register your own implementation class for those workflows before you can use corresponding functions in UsherSDK. For certain workflows registering a UI implementation class is optional. If you don’t register your own classes for such workflows, the workflow will proceed based on some default assumptions.

Required UI Classes

Make sure you register your implementation classes for the following UI workflows of UsherSDK before using corresponding functionalities. Otherwise, your app may not behave as expected, since the default behavior is provided to make UsherSDK work properly.

  • LoginUIClass
  • DeviceProvisioningUIClass
  • LocationConsentUIClass
  • PasscodeUIClass
  • GeoFenceUIClass
  • BluetoothConsentUIClass
  • PhotoUploadUIClass
  • UserAgreementUIClass
  • TimeRestrictionUIClass

Optional UI Classes

  • ServerSwitchUIClass
  • EmailRecoveryUIClass
  • BadgePickerUIClass
  • SSOConfirmationUIClass
  • RevokedUIClass

Corresponding UI class registration functions can be found in UsherSDK’s UI class registrations section.

UI Protocols

UsherSDK provides a couple of UI protocols that need to be conformed to with your own classes on app side to make UsherSDK work properly.

Let’s take LoginUIProtocol as an example:

/// The `LoginUIProtocol` is adopted by a class to present a user interface that prompts
/// the user to enter login credentials. Login credentials are required by the UsherSDK to
/// validate a user and restore a badge.
public protocol LoginUIProtocol {

/// Returns an instance of the class conforming to `LoginUIProtocol` protocol.
static func instance() -> LoginUIProtocol?

/// Prompts the user to login to the AD badge specified.
///
/// - Parameters:
///   - badge: The badge requiring login
///   - completion: Completion block to call once the user enters the credential.
///                 The completion block also takes a failureHandler block as a parameter that
///                 will be called in case login fails. Use this block to present error to user
///                 and/or retry login.
func promptForLoginToBadge(_ badge: Badge, completion: @escaping CredentialEntryCompletion)

/// Prompts the user to login to the AD badge in an organization.
///
/// - Parameters:
///   - orgName: The organization name.
///   - completion: Completion block to call once the user enters the credential.
///                 The completion block also takes a failureHandler block as a parameter
///                 that will be called in case login fails. Use this block to present error to user
///                 and/or retry login.
func promptForLoginToOrganization(_ orgName: String, completion: @escaping CredentialEntryCompletion)

/// Dismiss any UI presented by the `promptForLoginToBadge(_:completion:)` or
/// `promptForLoginToOrganization(_:completion:)` calls.
func dismiss()
}

In order to make your LoginViewController work with UsherSDK, you have to implement these functions defined in LoginUIProtocol.

More UsherSDK UI Protocols can be found in SDK UI Protocols section.