Getting Started

Quickstart guide for iOS projects using Keyless.

β€‹πŸš€ Lets get started!

In this Getting Started guide, we will add the Keyless SDK to your iOS mobile application project. This will allow you to enroll and authenticate users with the Keyless protocol.

Prerequisites

  • Install the following:

    • Xcode 10.1 or later

    • CocoaPods 1.4.0 or later

  • Make sure that your project meets the following requirements:

    • Your project must target iOS 12.4 or later.

    • Swift projects must use Swift 4.0 or later.

  • Set up a physical iOS device for running your app.

  • Enable Camera permissions: add the Privacy - Camera Usage Description key in your project’s Info.plist by adding the following (in XCode under Project > Info):

<key>NSCameraUsageDescription</key>
<string>Keyless needs access to your camera to enroll and authenticate you. Keyless cannot be used without your camera. Please allow camera permissions.</string>
  • Background processing. Enable the Background processing mode under Signing & Capabilities/Background Modes. Then, add the following in your project’s Info.plit (in XCode, under the key Permitted background task scheduler identifiers):

    <key>NSCameraUsageDescription</key>
    <key>BGTaskSchedulerPermittedIdentifiers</key>
    <array>
    <string>YOUR APP IDENTIFIER</string>
    </array>

Once you're ready with the prerequisites, let's get started.

β€‹πŸ‘¨πŸ”§ Installation

We recommend using CocoaPods to install the Keyless library.

Step 1: Create a Podfile if you don’t already have one:

$ cd your-project-directory
$ pod init

Step 2: Setup Cocoapods to use your Cloudsmith credentials, by running the following commands and replacing YOUR_CLOUDSMITH_TOKEN with the Cloudsmith token for partners provided you by Keyless.

git config --global credential.helper store
echo "https://token:[email protected]" >> ~/.git-credentials

Step 3: Add the KeylessSDK pod to your Podfile:

# -- This is the Keyless repository for partners. --
source 'https://dl.cloudsmith.io/basic/keyless/partners/cocoapods/index.git'
​
target 'MyApp' do
use_frameworks!
​
# Add the Keyless pod
pod 'KeylessSDK'
end

Step 4: Add the following at the bottom of the same file:

post_install do |installer|
installer.pods_project.targets.each do |target|
target.build_configurations.each do |config|
config.build_settings['ENABLE_BITCODE'] = 'NO'
end
end
end

Step 5: Install the pods. If pod prompts you for authentication insert the string token as your username and then fill in YOUR_CLOUDSMITH_TOKEN as the password.

$ pod install
Analyzing dependencies
Cloning spec repo `cloudsmith-basic-keyless-partners-cocoapods-index` from `https://dl.cloudsmith.io/basic/keyless/partners/cocoapods/index.git`
Username for 'https://dl.cloudsmith.io': token
Password for 'https://dl.cloudsmith.io': YOUR_CLOUDSMITH_TOKEN

Step 6: Finally, open your .xcworkspace file to see the project in Xcode:

$ open your-project.xcworkspace

Step 7: Disable Bitcode in the Build Settings of your target app (and every other target):

Enable Bitcode: NO

β€‹πŸ“± Initialisation

The final step is to add initialization code to your application to UIApplicationDelegate, your main UIViewController or any other class that is responsible for your app navigation.

Import the KeylessSDK module:

import KeylessSDK

Configure a Keyless shared instance, typically in your app’s application:didFinishLaunchingWithOptions: method:, or in viewDidLoad of any view controller. Pass in YOUR_KEYLESS_API_KEY and the class that will conform to KeylessDelegateProtocol.

override func viewDidLoad() {
super.viewDidLoad()
​
do {
try Keyless.configure(apiKey: "YOUR_KEYLESS_API_KEY", delegate: self)
} catch {
// Handle Error
print("Error configuring the Keyless SDK: \(error).")
}
}

β€‹πŸ›Έ Implementation

Implement the KeylessDelegateProtocol methods:

//Required Methods:
​
func enrollmentDidFinish(keylessID: String?, enrollmentResponse: String?, error: KeylessError?) {}
​
func authenticationDidFinish(token: String?, error: KeylessError?) {}
​
func deEnrollmentDidFinish(deEnrollmentResponse: String?, error: KeylessError?) {}
​
​
//Optional Methods:
​
func enrollmentDidProgress(progress: Float) {}
​
func enrollmentDidStart() {}
​
func authenticationDidStart() {}
​
func deEnrollmentDidStart() {}

Example implementation:

// MARK: - Keyless delegate
​
extension ViewController: KeylessDelegateProtocol {
​
// MARK: Required: -
​
func enrollmentDidFinish(keylessID: String?, enrollmentResponse: String?, error: KeylessError?) {
guard error == nil else {
print("Enrollment failed with error: \(error!).")
return
}
​
// Handle successful enrollment
}
​
func authenticationDidFinish(token: String?, error: KeylessError?) {
guard error == nil else {
print("Authentication failed with error: \(error!).")
return
}
​
// Handle successful authentication
}
​
func deEnrollmentDidFinish(deEnrollmentResponse: String?, error: KeylessError?) {
guard error == nil else {
print("DeEnrollment failed with error: \(error!).")
return
}
​
// Handle successful de-enrollment
}
​
​
// MARK: Optional: -
​
func enrollmentDidProgress(progress: Float) {
print("Enrollment progress: \(progress).")
}
​
func enrollmentDidStart() {
print("Enrollment started.")
}
​
func authenticationDidStart() {
print("Authentication started.")
}
​
func deEnrollmentDidStart() {
print("DeEnrollment started.")
}
​
}