Migrate to EncapSwiftAPI

About migrating to the EncapSwiftAPI

As Swift is moving along with ABI and Module stability, we want to provide an even better experience for developers that are using Swift. Our new API is more Swift-friendly, and it is easier to integrate and use.

You can find information below on how to migrate from the EncapAPI to the EncapSwiftAPI.

Note

The core operations are the same and will not require any changes when you migrate.

Set up the project

To learn how to set up the project, see our iOS SDK Getting started guide.

Migration guide

The purpose of this guide is to highlight the differences with the new API, and to give an overview of what is required to start using it.

Want to learn more?

If you want to look through complete code examples for all of the operations, then you can use the example project.

To learn more about the example project, see our Example project appendix.

EncapConfig

Improved initialisation of the EncapConfig using the initialisation with default parameters makes it easier to identify and set the minimum required configuration needed:

let encapConfig = EncapConfig(serverURL: "some value", applicationId: "some value", publicKey: "some value")

Important

Once you have migrated to the EncapSwiftAPI, EncapController.shared().config.applicationId = applicationId becomes EncapController.shared.config.applicationId = applicationId.

EncapController operations

All operations have an onCompletion block containing a Result type, giving either .success or .failure.

Want to learn more?

You can learn more about Result in the Apple developer documentation.

Example: Code block from loadConfig

/// Get server configuration parameters before start of activation, this call is optional and not needed in client only mode.
///
/// - Parameter onCompletion: The block that gives Result containing .success or .failure
public func loadConfig(onCompletion: @escaping (Result<LoadConfigResult, ErrorResult>) -> ())

What does cancelSession look like after migration?

The code blocks below show an example of migrating from the EncapAPI (Objective-C version) to the EncapSwiftAPI (Swift version) for cancelSession, in the example project.

The same pattern applies for all of the operations on the EncapController.

Want to learn more?

If you want to look through complete code examples for all of the operations, then you can use the example project.

To learn more about the example project, see our Example project appendix.

Example: Before migration

EncapController.shared.cancelSession(onSuccess: {
        self.stopAnimate()
        self.setState(.stateActivated)
        self.statusText.text = "Cancelled session"
}, onError: { errorResult in
        self.stopAnimate()
        self.handleError(errorResult, in: .stateCancelSession)
})

Example: After migration

EncapController.shared.cancelSession { result in
      self.stopAnimate()
      
      switch result {
          case .success(_):
              self.setState(.stateActivated)
              self.statusText.text = "Cancelled session"
      
          case .failure(let errorResult):
              self.handleError(errorResult, in: .stateCancelSession)
      }
}

EncapController Default Parameters

clientData is defaulted to nil in startAddOrUpdate and startAuthentication, so that the method signature can be simplified when clientData is not being used.

AuthMethod

EncapActivationParameters and EncapAuthParameter are removed in the EncapSwiftAPI. They are replaced with the new enum type AuthMethod.

@frozen public enum AuthMethod {

    case unknown

    case device

    case pin(value: String)

    /// Using kSecAccessControlBiometryCurrentSet
    /// Data is invalidated when fingers are added or removed.
    /// - Parameter prompt: The message displayed to the end-user when prompted to authenticate using Touch ID, for example context message sent from server.
    case strongTouchID(prompt: String?)

    /// Using kSecAccessControlBiometryCurrentSet.
    /// When Face ID is re-enrolled this item is invalidated.
    case faceID

    case offlineDevice

    case offlinePin(value: String)

    case offlineStrongTouchID(prompt: String?)

    case offlineFaceID
}

Useful information

The following have an associated value:

• pin
• strongTouchID
• offlinePin
• offlineStrongTouchID

In some cases, it can be useful to use the rawValue() for comparison when the value should not be taken in consideration.

Example: finishActivation with .faceID

EncapController.shared.finishActivation(withAuthMethod: .faceID, onCompletion: ...

Example: finishAuthentication with .faceID

EncapController.shared.finishAuthentication(withAuthMethod: .faceID, onCompletion: ...

EncapInputType name change

EncapInputType is changed to InputType:

@frozen public enum InputType {

    case any
    case numeric
    case alpha
    case alphaNumeric

    public func toUIKeyboardType() -> UIKeyboardType
    public func isValidFor(string: String) -> Bool
}