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:

To register the user’s faces and add them as templates for future authentication,
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 in Your Xcode Project

Follow these steps to add Ver-ID to your Xcode project:

Request an API secret for your app.
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>
```
Select your app target, click on the General tab and scroll down to Embedded binaries.
Click the + button on the bottom of the pane and add VerID.framework.
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.
As an alternative to the previous step you can place the downloaded zip archive on a remote server. This will cut the initial download size of your app. 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>http://my.domain/path/to/resources.zip</string>
```

Getting Started with the Ver-ID API

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

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.
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.
Receive a result from the session
- When the session finishes it will call session:_:didFinishWithResult on your view controller.
- Inspect the result object for details of the session’s outcome.
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.

Ensure your view controller implements VerIDSessionDelegate.

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
}

If the user is already registered authenticate her/him before registering new faces. See Authentication.

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;

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];

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.

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

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;

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];

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.

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];

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:

Run a registration session.

let settings = VerIDRegistrationSessionSettings(userId: "some user id")
let session = VerIDRegistrationSession(settings: settings)
session.delegate = self
session.start()

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
        }
    }
}

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

Added User Manager

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.