API Reference

PrivakeyCX

public class PrivakeyCX : NSObject

Swift API library for interacting with the PrivakeyCX server.

Summary

Here is a list of all public methods with a quick description. Further down the page, they are all listed in more detail with any relevant examples. Click on any method to go to its detailed description.

Note: Many of the methods utilize completion handlers to return their results, due to their asynchronous nature. For more info on this, see the Swift documentation on Closures.

Public Constructors

init

public convenience override init ()

Initializes Privakey with the default CX API, CoreData data service, Apple’s Local Authentication Context for biometry, and the default Pin Entry Manager.

public init ( apiService: APIService, dataService: DataManager, localAuthenticationService: LocalAuthenticationManager, pinEntriesService: PinEntriesManager )

Initializes Privakey with the given custom services to facilitate testing and customization using dependency injection.

Public Properties

delegate

public weak var delegate : PrivakeyCXDelegate?

Assign a PrivakeyCXDelegate to this property to handle certain asynchronous events. For more info, see the Delegates page.

uiDelegate

public weak var uiDelegate: PinEntriesManagerUIDelegate?

Assign a delegate to this property to update the UI for failed PIN entry events. We recommend updating your view to let the user know how many PIN entry attempts they have remaining, and adding an additional warning if they only have 1 attempt remaining, as they will be revoked if they fail at that point.

Public Methods

getVersion

public func getVersion () -> String

Returns the current version of the library, in the form X.Y.Z

enablePrivakey

public func enablePrivakey ( password: String, notificationId: String, notificationFramework: String, deviceName: String, appSpaceGuid: String, sessionToken: String, completion: @escaping ( _ success: Bool?, _ error: Error? ) -> Void )

Enable Privakey for an account. Keys are generated for use with Privakey, binding this device to the user's Privakey account.

A user should authenticate with your server, your server will then contact the CX Server to create or retrieve a Privakey account. The CX Server will return a privakeyId and a sessionToken. This call will generate the required Keypairs and register the device with the CX Server. After the device is enrolled and the account has been created the device will be able to process requests.

addAppSpaceCredential

public func addAppSpaceCredential ( password: String, appSpaceGuid: String, sessionToken: String, completion: @escaping ( _ success: Bool?, _ error: Error?) -> Void )

Add an additional credential for a new AppSpace. For your first AppSpace, you should call enablePrivakey() instead of this.

addAppSpaceCredentialBiometric

public func addAppSpaceCredentialBiometric ( appSpaceGuid: String, sessionToken: String, bioPromptText: String?, completion: @escaping ( _ success: Bool?, _ error: Error?) -> Void )

Add an additional credential for a new AppSpace. This function uses the user's biometrics instead of a PIN/password. For your first AppSpace, you should call enablePrivakey().

isBiometricSensorAvailable

public func isBiometricSensorAvailable ( completion: @escaping ( _ isAvailable: Bool, _ message: String ) -> Void )

Queries the system to see if a biometric sensor is available and ready for use.

isBiometricEnabled

public func isBiometricEnabled ( completion: @escaping ( _ success: Bool, _ error: Error? ) -> Void )

Queries the system to see if a user has explicitly enabled biometric authentication for the implementing app.

enableBiometric

public func enableBiometric ( password: String, bioPromptText: String?, completion: @escaping ( _ success: Bool?, _ error: Error? ) -> Void )

Enables PrivakeyCX to accept biometrics for authentications. E.G. Touch ID or Face ID.

isBound

public func isBound ( completion: @escaping ( _ isBound: Bool, _ error: Error? ) -> Void )

Determines if this device is currently bound to any App Spaces. Useful for E.G. checking during the launch of your app if it's a new user or existing one.

disableBiometric

public func disableBiometric ( completion: @escaping ( _ success: Bool?, _ error: Error? ) -> Void )

Disabled PrivakeyCX support for biometrics (Touch ID/Face ID). Only a PIN/password will be allowed to authorize requests.

changePassword

public func changePassword ( oldPassword: String, newPassword: String, completion: @escaping ( _ success: Bool?, _ error: Error? ) -> Void )

Allows a user to change their PIN/password.

validatePassword

public func validatePassword ( password: String ) -> Bool

Validates an entered PIN/Password. Invalid PIN attempts are protected by the Pin Entries Manager which disables the device after the max attempts have been used.

disablePrivakeyCX

public func disablePrivakeyCX ( completion: @escaping ( _ success: Bool?, _ error: Error? ) -> Void )

Deletes all the PrivakeyCX data and notifies the server that PrivakeyCX has been disabled for this device.

revokeDevice

public func revokeDevice ( appSpaceGuid: String, completion: @escaping ( _ success: Bool?, _ error: Error? ) -> Void )

Disables and deletes keys used for authorizing requests from the given App Space. To authorize requests related to that App Space again, the device will have to be re-added via the binding process.

getDevices

public func getDevices ( status: DeviceStatus, completion: @escaping (_ devices: [PrivakeyDevice]?, _ error: Error? ) -> Void )

A device search method. Use this method to return select devices based on their status, that are bound to the Privakey account.

getCurrentDevice

public func getCurrentDevice ( completion: @escaping ( _ device: PrivakeyDevice?, _ error: Error? ) -> Void )

Gets the locally cached device information.

getDevice

public func getDevice ( deviceGuid: String, completion: @escaping ( _ device: PrivakeyDevice?, _ account: PrivakeyAccount?, _ error: Error? ) -> Void )

Gets information for a specific device. The specified device must belong to the same account as the calling device.

updateDevice

public func updateDevice ( name: String, notificationFramework: String, notificationId: String, completion: @escaping ( _ success: Bool?, _ error: Error? ) -> Void )

Updates some of the device specific information. You are required to call this method when your app’s notification token or ID changes to continue receiving notifications from the CX Server.

📘

Push Notifications

Use updateDevice() to update the NotificationId on the CX server. The notificationId must always be current to continue receiving push notifications from the CX Server.

getRequestByGuid

public func getRequestByGuid ( appSpaceGuid: String, requestGuid: String, completion: @escaping ( _ request: PrivakeyRequest?, _ error: Error? ) -> Void )

Gets a single request based on its identifier.

If the request exists in local cache, the cached item will be returned via completion. At the same time, a call will be made to the CX Server to get the latest data for the request. When this call returns, the data will be sent through PrivakeyCXDelegate.onGetRequestsResult(). See the Delegates page for more info.

If the request does not exist in local cache, the call to the CX Server is made and its data is returned through completion.

getRequestsByStatus

public func getRequestsByStatus ( appSpaceGuid: String, requestStatus: RequestStatus, completion: @escaping ( _ requests: [PKRequest]?, _ error: Error? ) -> Void )

Get all requests of a certain status for a particular App Space. This method is a shorthand for the other method, getRequests().

getRequests

public func getRequests ( appSpaceGuid: String, requestStatus: RequestStatus?, beginDate: Date?, endDate: Date?, limit: Int?, completion: @escaping ( _ requests: [PKRequest]?, _ error: Error? ) -> Void )

Request search method. This will return all the requests that meet the specified conditions.

processRequest

public func processRequest ( appSpaceGuid: String, requestGuid: String, password: String?, selectedButtonIndex: Int, responseContent: String?, completion: @escaping ( _ success: Bool?, _ error: Error? ) -> Void )

Processes the given request. This tells the Privakey CX server that you have confirmed an action on the request.

processRequestBiometric

public func processRequestBiometric ( appSpaceGuid: String, requestGuid: String, selectedButtonIndex: Int, responseContent: String?, biometricAuthReason: String, completion: @escaping ( _ success: Bool?, _ error: Error? ) -> Void )

Processes the given request using a biometric. This tells the Privakey CX server that you have confirmed an action on the request.

requestNotificationActedOn

public func requestNotificationActedOn ( notificationUserInfo: [AnyHashable: Any] )

Uploads telemetry data for the event that a request notification is clicked. Call this method from within you App Delegate's notification handler, E.G. inside of:

func userNotificationCenter(_ center: UNUserNotificationCenter, didReceive response: UNNotificationResponse, withCompletionHandler completionHandler: @escaping () -> Void)

requestViewStart

public func requestViewStart ( request: PrivakeyRequest )

Initiates the process of uploading a request viewed telemetry event. Call this method whenever request content is being displayed in the app. Once the view goes off screen, be sure to call requestViewEnd(request) to complete the process.

requestViewEnd

public func requestViewEnd ( request: PrivakeyRequest )

Completes the process of uploading a request viewed telemetry event. Call this method whenever request content is done being displayed in the app. It should be called as a followup to requestViewStart(request), above.

handlePrivakeyNotification

public func handlePrivakeyNotification ( notificationUserInfo: [AnyHashable : Any], completion: @escaping ( _ didRevokeDevice: Bool ) -> Void )

Processes Privakey notifications. Forward any received Privakey notifications to this method. If a notification to revoke is received, then didRevokeDevice will be true and you should clear your app data accordingly.

checkStatus

public func checkStatus ( completion: @escaping ( _ didRevokeDevice: Bool, _ didSuspendAccount: Bool ) -> Void )

Checks if the current device or associated account status has changed and handles it appropriately. If the device is revoked, then didRevokeDevice will be true and you should clear your app data accordingly. If the account was suspended, then didSuspendAccount will be true and you should update the UI accordingly.