Skip to content
Deprecated. Please Ver-ID-UI-iOS.
Branch: master
Clone or download
Latest commit 83f78e4 Feb 27, 2019
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
Assets.xcassets Updated app icon Jan 5, 2019
Settings.bundle
Ver-ID Sample.xcodeproj
VerIDModels Updated to version 3.4.0 Aug 10, 2018
docs update Sep 27, 2018
.gitattributes Fixed resource hashes Apr 11, 2018
.gitignore
AppDelegate.swift Use Ver-ID 3.5.0 Dec 13, 2018
ErrorViewController.swift Use app delegate reload method to reload Ver-ID in case of failure Nov 23, 2018
ExportCodeViewController.swift Added support for export and import of face templates Nov 23, 2018
Info.plist Use Ver-ID 3.5.0 Dec 13, 2018
IntroViewController.swift Use new registration downloading and uploading protocols Nov 27, 2018
LaunchScreen.storyboard
MainSwift.storyboard Use app delegate reload method to reload Ver-ID in case of failure Nov 23, 2018
MainViewController.swift Use new registration downloading and uploading protocols Nov 27, 2018
Podfile Updated to Ver-ID version 3.5.1 Dec 13, 2018
Podfile.lock Updated to Ver-ID version 3.5.1 Dec 13, 2018
QRCodeScanViewController.swift
README.md Added CocoaPods badge Feb 27, 2019
RegistrationData.swift
RegistrationDownloading.swift Specify registration downloading and uploading protocols and model Nov 27, 2018
RegistrationImportViewController.swift
RegistrationUploading.swift Specify registration downloading and uploading protocols and model Nov 27, 2018

README.md

Cocoapods

Ver-ID Face Authentication SDK

Introduction

Ver-ID gives your application the ability to authenticate users by their faces. Ver-ID replaces the need to remember and type passwords. Ver-ID stores all its assets on the client making the entire face authentication process available offline.

Your application will interact with Ver-ID in two tasks:

  1. To register the user's faces and add them as templates for future authentication,
  2. To authenticate the user on subsequent visits.

Tasks

User registration

Before the user can authenticate Ver-ID needs to acquire a number of images of the user's face. These images serve as templates used for comparison at the time of authentication. Your app instructs Ver-ID to register the user. Ver-ID then attempts to register the user and returns a result of the registration session. After successful registration the user is able to authenticate using her/his face.

Your app may register additional faces for an authenticated user to extend the probability of positive authentication under varying ambient lighting conditions.

Authentication

Ver-ID can only authenticate users who have previously registered (see previous section). Your app can ask Ver-ID to either authenticate a specific user or to identify and authenticate any registered user. This means your registered users may not even need to enter their user name to authenticate.

Liveness Detection

If you need ensure that the user in front of the camera is a live person and not a picture or video impersonation you can use Ver-ID's liveness detection feature. Ver-ID will ask the user to turn in random directions.

Adding Ver-ID to Your Xcode Project

Using CocoaPods

  1. Add Ver-ID pod in your Podfile:

    pod 'Ver-ID', '~> 3.5'
  2. Install the dependencies using pod install.*

  3. Open the generated xcworkspace in Xcode.

*If you receive an error [!] Unable to find a specification for Ver-ID (~> 3.5) try running pod repo update before trying pod install again.

Manual Installation

  1. Download zip file containing the Ver-ID framework.
  2. Unzip the downloaded archive and place VerID.framework in your Xcode project's directory.
  3. Open your project in Xcode.
  4. Select File/Add Files to "your project name"... and add the downloaded VerID.framework.
  5. Select your app target, click on the General tab and scroll down to Embedded binaries.
  6. Click the + button on the bottom of the pane and add VerID.framework.

Project Setup

  1. Request an API secret for your app.

  2. In Xcode open your project's Info.plist file and add the following entry, substituting [your API secret] for the API secret received in step 1.

    <key>com.appliedrec.verid.apiSecret</key>
    <string>[your API secret]</string>
  3. Download Ver-ID resources and add them to your app:

    1. In your project's folder create a folder called VerIDModels.
    2. Download ... and unzip it in to the VerIDModels folder created in the previous step.
    3. In Xcode select File/Add Files to "your project name"...
    4. Select the downloaded VerIDModels folder and under Options select Create folder references.
  4. As an alternative to the previous step you can place the downloaded zip archive on a remote server. Ver-ID will download its resources on first run of your app making the app download smaller but the first run of the app slower. Add the following entry into your app's Info.plist replacing the URL with the zip file address on your server:

    <key>com.appliedrec.verid.resourcesURL</key>
    <string>https://ver-id.s3.amazonaws.com/resources/models/v1/VerIDModels.zip</string>
  5. Select your app target and click on the Build Settings tab. Under Build Options set Enable Bitcode to No.

  6. You can now import the Ver-ID framework in your Swift files using import VerID.

Getting Started with the Ver-ID API

There are 4 steps you will follow in a normal Ver-ID session:

  1. Load Ver-ID
    • If you specify the Ver-ID API secret in your Info.plist file you can skip this step and let Ver-ID load implicitly.
    • You may explicitly load Ver-ID if you want to show a loading page while Ver-ID loads and present a specific view controller depending on the success of the load operation. See AppDelegate in the Ver-ID SDK sample app for an example.
    • To load Ver-ID call VerID.shared.load.
  2. Launch a Ver-ID session
    • Implement VerIDSessionDelegate in your view controller.
    • Create an settings object for your particular session (e.g. VerIDRegistrationSessionSettings)
    • Create an instance of a VerIDSession subclass (e.g. VerIDRegistrationSession) with the settings object created in the previous step.
    • Set your view controller as the delegate of the session instance.
    • Start the session by calling the session's start method.
  3. Receive a result from the session
  4. Unload Ver-ID
    • You may call VerID.shared.unload to free up disk resources used by Ver-ID.

Registration

Following are the exact steps your application should take to register a user.

  1. Ensure your view controller implements VerIDSessionDelegate.

  2. Check that your user is not already registered. Do not run this code on the main queue as it may hold up your app.

    Swift

    let userId = "myUserId"
    do {
        if try VerID.shared.isUserRegistered(userId) == true {
            // User is registered
        } else {
            // User is not registered
        }
    } catch {
        // The call failed
    }

    Objective-C

    NSString *userId = @"myUserId";
    NSError *error;
    // Load the registered users
    NSArray<VerIDUser *> *users = [[VerID shared] registeredVerIDUsersAndReturnError:&error];
    if (error == NULL) {
        NSEnumerator *userEnumerator = [users objectEnumerator];
        VerIDUser *user;
        // Enumerate over users and see if our user is registered
        while (user = [userEnumerator nextObject]) {
            if ([[user userId] isEqualToString:[VerIDUser defaultUserId]]) {
                // User is registered
                return;
            }
        }
        // User is not registered
    } else {
        // The call failed
    }
  3. If the user is already registered authenticate her/him before registering new faces. See Authentication.

  4. Create registration settings.

    Swift

    let settins = VerIDRegistrationSessionSettings(userId: userId)
    // If you wish to show the result of the session to the user
    settings.showResult = true

    Objective-C

    VerIDRegistrationSessionSettings *settings = [[VerIDRegistrationSessionSettings alloc] initWithUserId:[VerIDUser defaultUserId] livenessDetection:VerIDLivenessDetectionRegular showResult:NO];
    // If you wish to show the result of the session to the user
    settings.showResult = YES;
  5. Create a registration session instance, set its delegate and start the session.

    Swift

    let session = VerIDRegistrationSession(settings: settings)
    session.delegate = self
    session.start()

    Objective-C

    VerIDRegistrationSession *session = [[VerIDRegistrationSession alloc] initWithSettings:settings];
    [session setDelegate:self];
    [session start];
  6. Receive the result of the session in your view controller.

    Swift

    func session(_ session: VerIDSession, didFinishWithResult result: VerIDSessionResult) {
        // Inspect the result
        // Some examples:
        if result.isPositive {
        	// The user finished the registration
        }
        if let imageURL = result.images.first {
        	// This is the URL of the first "selfie" image collected in the session
        	// The image will be deleted next time Ver-ID is loaded or when you call unload. 
        	// Copy it somewhere if you wish to retain it across sessions.
        }
    }

    Objective-C

    - (void)session:(VerIDSession * _Nonnull)session didFinishWithResult:(VerIDSessionResult * _Nonnull)result {
        // Inspect the result
    	// Some examples:
    	if ([result isPositive]) {
    	    // The user finished the registration
    	}
    	NSURL *imageURL = [[result images] firstObject];
    	if (imageURL != NULL) {
    	    // This is the URL of the first "selfie" image collected in the session
    	    // The image will be deleted next time Ver-ID is loaded or when you call unload. 
    	    // Copy it somewhere if you wish to retain it across sessions.
    	}
    }

Authentication

Follow these steps to authenticate any user who previously registered in your app without asking for a user name or password.

  1. Ensure the user is registered (see step 2 of Registration)

  2. Create authentication settings.

    Swift

    let settings = VerIDAuthenticationSessionSettings(userId: userId)
    // If you wish to show a guide on how to authenticate to the user
    settings.showResult = true

    Objective-C

    VerIDAuthenticationSessionSettings *settings = [[VerIDAuthenticationSessionSettings alloc] initWithUserId:userId livenessDetection:VerIDLivenessDetectionRegular];
    // If you wish to show the result of the session to the user
    settings.showResult = YES;
  3. Create an authentication session instance, set its delegate and start the session.

    Swift

    let session = VerIDAuthenticationSession(settings: settings)
    session.delegate = self
    session.start()

    Objective-C

    VerIDAuthenticationSession *session = [[VerIDAuthenticationSession alloc] initWithSettings:settings];
    [session setDelegate:self];
    [session start];
  4. Receive the result of the session in your view controller.

    Swift

    func session(_ session: VerIDSession, didFinishWithResult result: VerIDSessionResult) {
        // Inspect the result
        // Some examples:
        if result.isPositive {
        	// The user has authenticated
        }
        if let imageURL = result.images.first {
        	// This is the URL of the first "selfie" image collected in the session
        	// The image will be deleted next time Ver-ID is loaded or when you call unload. 
        	// Copy it somewhere if you wish to retain it across sessions.
        }
    }

    Objective-C

    - (void)session:(VerIDSession * _Nonnull)session didFinishWithResult:(VerIDSessionResult * _Nonnull)result {
        // Inspect the result
    	// Some examples:
    	if ([result isPositive]) {
    	    // The user has authenticated
    	}
    	NSURL *imageURL = [[result images] firstObject];
    	if (imageURL != NULL) {
    	    // This is the URL of the first "selfie" image collected in the session
    	    // The image will be deleted next time Ver-ID is loaded or when you call unload. 
    	    // Copy it somewhere if you wish to retain it across sessions.
    	}
    }

Liveness Detection

Follow these steps to ensure the user holding the device is a live person.

  1. Create a liveness detection session instance, set its delegate and start the session.

    Swift

    let session = VerIDLivenessDetectionSession(settings: nil)
    session.delegate = self
    session.start()

    Objective-C

    VerIDLivenessDetectionSession *session = [[VerIDLivenessDetectionSession alloc] initWithSettings:NULL];
    [session setDelegate:self];
    [session start];
  2. Receive the result of the session in your view controller.

    Swift

    func session(_ session: VerIDSession, didFinishWithResult result: VerIDSessionResult) {
        // Inspect the result
        // Some examples:
        if result.isPositive {
        	// The user provided a live "selfie"
        }
        if let imageURL = result.images.first {
        	// This is the URL of the first "selfie" image collected in the session
        	// The image will be deleted next time Ver-ID is loaded or when you call unload. 
        	// Copy it somewhere if you wish to retain it across sessions.
        }
    }

    Objective-C

    - (void)session:(VerIDSession * _Nonnull)session didFinishWithResult:(VerIDSessionResult * _Nonnull)result {
        // Inspect the result
    	// Some examples:
    	if ([result isPositive]) {
    	    // The user provided a live "selfie"
    	}
    	NSURL *imageURL = [[result images] firstObject];
    	if (imageURL != NULL) {
    	    // This is the URL of the first "selfie" image collected in the session
    	    // The image will be deleted next time Ver-ID is loaded or when you call unload. 
    	    // Copy it somewhere if you wish to retain it across sessions.
    	}
    }

User Management

The UserManager class allows you to export and import registered users' face templates for use on your back end or to share them among multiple devices.

Adding users

There are three ways to add users:

  1. Run a registration session.

    let settings = VerIDRegistrationSessionSettings(userId: "some user id")
    let session = VerIDRegistrationSession(settings: settings)
    session.delegate = self
    session.start()
  2. Run a liveness detection session with includeFaceTemplatesInResult of its settings set to true and add the collected templates to the user manager.

    let settings = VerIDLivenessDetectionSessionSettings()
    settings.includeFaceTemplatesInResult = true
    let session = VerIDLivenessDetectionSession(settings: settings)
    session.delegate = self
    session.start()

    Then in your delegate:

    func session(_ session: VerIDSession, didFinishWithResult result: VerIDSessionResult) {
        guard result.isPositive else{
        	return
        }
        let templates: [FaceTemplate] = result.facesSuitableForRecognition.compactMap({$0.faceTemplate})
        if templates.isEmpty {
        	return
        }
        let userManager = UserManager()
        userManager.assingFaceTemplates(templates, to: "some user id") { error in
        	if error == nil {
        		// Face templates added to the user
        	}
        }
    }
  3. Register user from an image:

    guard let image = UIImage(contentsOfFile: "path/to/myimagefile.jpg") else {
        return
    }
    do {
    	let face = try VerID.shared.detectFaceInImage(image, keepForRecognition: true)
    	try VerID.shared.registerFaces([face], asUser: "some user id")
    }

Exporting users' face templates

let userManager = UserManager()
userManager.exportFaceTemplates { templates, error in
	if error == nil {
		// The exported dictionary object contains arrays of FaceTemplate objects.
		// The dictionary is keyed by the user id.
		for (userId, userTemplates) in templates {
			// The FaceTemplate class conforms to the Codable protocol.
			// You may for example export the face templates as JSON:
			do {
				let jsonData = try JSONEncoder().encode(userTemplates)
			} catch {
			}
		}
	}
}

Importing face templates

let data: Data = ... // JSON-encoded user face template data
let userManager = UserManager()
do {
	let templates = try JSONDecoder().decode([String:[FaceTemplate]].self, from: data)
	userManager.importFaceTemplates(templates) { error in
		if error == nil {
			// The face templates are now imported
		}
	}
} catch {
}

Advanced Use

Ver-ID provides low-level functions for face detection and recognition if you prefer to supply the images yourself.

Face detection

guard let image = UIImage(contentsOfFile: "path/to/myimagefile.jpg") else {
    return
}
guard let face = try? VerID.shared.detectFaceInImage(image, keepForRecognition: true) else {
    return
}

Registration

let userId = "myUserId"
guard let user = try? VerID.shared.registerFaces([face], asUser: userId) else {
    return
}

Authentication

guard let authenticated = try? VerID.shared.authenticateUser(id: user.userId, inFaces: [face]) else {
    return
}
if authenticated {
    // The user is authenticated
}

Cleanup

Discard the faces used for authentication. Keep the faces that were used for registration.

VerID.shared.discardFaces([face])

Documentation

Full API documentation is available on the project's Github page.

Release Notes

3.4.0

Deprecated UserManager.addFaceTemplates(_:to:). If you use it it will create a new face template even if the template already exists for a different user. This may be useful for testing with a limited set of templates but likely not something you want in production.

The UserManager.addFaceTemplates(_:to:) is replaced by UserManager.assignFaceTemplates(_:to:). The new function will look if the template is already assigned to a different user and if it is it will remove it from the current user before adding it to the user specified in this call.

To illustrate the difference between the two methods take this example: If you call the old add method 100 times assigning the template to a different new user each time you'll end up with 100 users with one template each. Running the same operation with new assign method you will end up with 1 user (the last one you called the assign with) with 1 template.

Secondly we deprecated the UserManager.removeFaceTemplates(_:from:) method and replaced it with a better-performing UserManager.deleteFaceTemplates(_:) method. The new method will simply delete templates from all users.

3.2.0

  • Improved performance

3.1.0

3.0.0

  • Reduced download size of the library:
    • Ver-ID's resources like model files are no longer bundled with the library. Resource files need to be bundled in your app's assets folder.
    • Ver-ID's resources may also be loaded from a URL you specify when loading the library.
  • Added the ability to record a video of the session. In an instance of VerIDSessionSettings or its subclass specify videoURL. The returned VerIDSessionResult will have its videoURL property set if successfully recorded.
You can’t perform that action at this time.