Getting started

This topic outlines how the API is set up, how the iOS SDK generally works, and what the requirements are. The iOS SDK is distributed as all in one framework: OneginiSDKiOS.xcframework.

General setup of the iOS SDK

Client

The main interface of the iOS SDK is the Client. This protocol exposes the other client objects (UserClient and DeviceClient) that you can access. The SharedClient is a structure having shared single instance. The other clients that can be accessed through the Client are:

UserClient only contains user-related functionality. DeviceClient only contains device related functionality.

Thread safety

All methods that you call on the iOS SDK must be performed on the main thread of your mobile application. The iOS SDK will not enforce this. You may experience strange behavior if you do not execute the methods on the main thread. Internally the iOS SDK will use multiple threads to make sure it does not block the main thread.

Keychain sharing

Keychain sharing is not supported by the iOS SDK and cannot be enabled for the application.

Delegating control between the app and the iOS SDK

To use the iOS SDK functionality, you must integrate it into your application. Your application can trigger an iOS SDK function by calling an iOS SDK method. The functionality that the iOS SDK provides sometimes require interaction with the user. The iOS SDK itself does not contain any UI but will request you to implement specific actions (that require a UI) for your end-users.

Let's take user authentication as an example. The other methods take a similar approach, so when you understand the concept it should be easy to follow.

Example: User authentication

To begin user authentication, you must call the UserClient.authenticateUser() method. Below is an example of this method call (taken from the iOS example app):

    func login(profile: UserProfile, authenticator: Authenticator? = nil) {
        SharedUserClient.instance.authenticate(user: profile, with: authenticator, delegate: self)
    }

    /// Delegate methods

    func userClient(_ userClient: UserClient, didReceivePinChallenge challenge: PinChallenge) {
        // Ask the user for their PIN
    }

    func userClient(_ userClient: UserClient, 
                    didAuthenticateUser profile: UserProfile, 
                    authenticator: Authenticator, 
                    info customAuthInfo: CustomInfo?) {
        // Authentication was successful
    }

    func userClient(_ userClient: UserClient, 
                    didFailToAuthenticateUser profile: UserProfile, 
                    authenticator: Authenticator, 
                    error: Error) {
        // Authentication failed
    }

- (void)authenticateUser:(ONGUserProfile *)user
{
    [[ONGUserClient sharedInstance] authenticateUser:user delegate:self];
}

/// Delegate methods

- (void)userClient:(ONGUserClient *)userClient didReceivePinChallenge:(ONGPinChallenge *)challenge
{
    // Ask the user for their PIN
}

- (void)userClient:(ONGUserClient *)userClient didAuthenticateUser:(ONGUserProfile *)userProfile authenticator:(ONGAuthenticator *)authenticator info:(nullable ONGCustomInfo *)customAuthInfo
{
    // Authentication was successful
}

- (void)userClient:(ONGUserClient *)userClient didFailToAuthenticateUser:(ONGUserProfile *)userProfile authenticator:(ONGAuthenticator *)authenticator error:(NSError *)error
{
    // Authentication failed
}

In addition, the second parameter that you must provide is a delegate. The delegate is responsible for reporting whether the result of the triggered action was successful. However, as part of the authentication, a few other things happen. Depending on the authentication method that is preferred for a user, the user will be requested to enter their PIN or perform biometric authentication.

The delegate contains methods that will be called by the iOS SDK to hand over control to the application.

In the case of PIN authentication, the userClient(_:didReceivePinChallenge:) method is called by the iOS SDK. That method invocation contains a challenge object. A challenge object contains a number of things. Some metadata about the incoming request, optionally an error and a sender object. The error object will only be present if a previous invocation of the userClient(_:didReceivePinChallenge:) failed because the user entered an incorrect PIN. This also implies that on consecutive PIN attempts for a user, the userClient(_:didReceivePinChallenge:) method is called again. The sender object is the way to hand over the control from the app back to the iOS SDK. In the case of PIN authentication, this sender object must be used to provide the PIN to the iOS SDK so it can confirm it. The sender object can also be used to cancel a specific flow using the cancel: method. After you have cancelled the flow the userClient(_:didFailToAuthenticateUser:authenticator:error:) method is called to indicate that the authentication flow failed.

Error handling

Interaction with the iOS SDK can result in errors.

Supported platform versions

The minimum iOS version supported by the iOS SDK is 13.0.

Third-party dependencies

The iOS SDK uses a number of commercial and open-source third-party libraries. These are included in the framework and need NOT to be configured in the build settings of your app project workspace. These dependencies are linked to the iOS SDK statically and are prefixed, which means these will NOT create naming collisions. The iOS SDK is distributed as all in one framework: OneginiSDKiOS.xcframework.

External library dependencies