Latest 1.0.2
Homepage https://github.com/hyperverge/lending-utils-ios-sdk
Platforms ios 9.0
Dependencies FacebookLogin, FBSDKLoginKit

HVLendingUtils Framework Documentation

Introduction

HVLendingUtils is HyperVerge’s proprietary iOS Utilities Framework for banking and financial services industries. It has a module for verification and validation of user’s facebook profile using intelligence built over HyperVerge’s inhouse deep learning face recognition system.

Requirements

  • Minimum iOS Deployment Target – iOS 9.0

Example Project

  • Please refer to the example app provided in the repo to get an understanding of the implementation process.
  • To run the app, clone/download the repo and open example/HVLendingUtilsDemoApp.xcworkspace.
  • In FBLoginViewController add the appId and appKey provided to you by HyperVerge.
  • Build and run the app.

Integration Steps

1. Add the frameworks to your project

Via CocoaPods (Recommended)

HVLendingUtils is available through CocoaPods. To install
it, simply add the following line to your Podfile:

pod 'HVLendingUtils'

This will also add all the required Facebook dependencies to your project.

Manually
  • Unzip ‘HVLendingUtilsDependencies.zip’ and add the containing frameworks to your Xcode project. This includes all the frameworks required for facebook login.
  • Navigate to Targets -> General and include all the six frameworks under ‘Embedded Binaries’ and ‘Linked Frameworks and Libraries’.
  • Navigate to Targets -> ‘Your App name’ -> Build Settings. Ensure that ‘Always Embed Swift Standard Libraries’ is set to ‘Yes’.

2. Create a Facebook acccount

  • Open the Facebook Apps dashboard : https://developers.facebook.com/apps.
  • Click on the ‘Add a new App’ button. Give the app name and email ID and create the app. You will be redirected to a new page.
  • In the new page, select ‘Settings’ -> ‘Basic’ in the left navigation.
  • Click ‘Add Platform’ at the bottom of the page and select iOS.
  • Copy your app’s bundle identifier from Xcode and paste it in the Bundle ID field.
  • Click Save Changes at the bottom of the App Dashboard window.

3. Configure info.plist

  • In Xcode, right-click your project’s Info.plist file and select Open As -> Source Code.
  • Insert the following XML snippet into the body of your file just before the final element. Make sure you
<key>CFBundleURLTypes</key>
<array>
<dict>
<key>CFBundleURLSchemes</key>
<array>
<string>fb{your-app-id}</string>
</array>
</dict>
</array>
<key>FacebookAppID</key>
<string>{your-app-id}</string>
<key>FacebookDisplayName</key>
<string>{your-app-name}</string>
<key>LSApplicationQueriesSchemes</key>
<array>
<string>fbapi</string>
<string>fb-messenger-share-api</string>
<string>fbauth2</string>
<string>fbshareextension</string>
</array>

Please note that the app ID occurs in two locations in the above code and one of them requires the app ID to be preceded by ‘fb’.

4. Present the ViewController:

All interactions with the Facebook framework and the corresponding Hyperverge server call for face match happens from a ViewController called ‘HVFBManagerViewController’.
HVFBManagerViewController has a simple activity Indicator at the center of the view. If more customization is required, you could inherit this ViewController and add your own UI elements to it.
Please note that, if you are overriding viewDidAppear in the subclass, you should call super.viewDidAppear at the beginning of the method.

Presenting the ViewController requires instantiating it and setting up some required properties. The variables in the following example code are described later.

Swift:


    //1. Instantiate the ViewController

    let vc = storyboard?.instantiateViewController(withIdentifier: "ChildViewController") as! ChildViewController
    [OR]
    let bundle = Bundle(for: HVLendingUtils.self)
    let vc = UIStoryboard(name: HVLendingUtils.StoryBoardName, bundle:bundle).instantiateViewController(withIdentifier: "HVFBManagerViewController") as! HVFBManagerViewController

    //2. Set ViewController properties (described later)

      vc.setProperties(imageUri!, completionHook: completionHook, appId: appId, appKey: appKey,completionHandler:completionHandler)

    //3. Present the ViewController

    self.present(vc, animated: true, completion: nil)

Objective C:

    //1. Instantiate the ViewController

    ChildViewController * vc = [storyboard instantiateViewControllerWithIdentifier:@"ChildViewController"];

    [OR]

    NSBundle *bundle  = [NSBundle bundleForClass:[HVLendingUtils self]];
    UIStoryboard *storyboard = [UIStoryboard storyboardWithName:HVLendingUtils.StoryBoardName bundle: bundle];
    HVFBManagerViewController * vc = [storyboard instantiateViewControllerWithIdentifier:@"HVFBManagerViewController"];

    //2. Set ViewController properties (described later)

    [vc setProperties:imageUri appId:appId appKey:appKey completionHook:completionHook completionHandler:^(NSError *error, NSDictionary<NSString *,id> *result){

        if(error != nil){
            printf("Error!");
        }else{
            printf("Success!");
            }
        }];

    //3. Present the ViewController

    [self presentViewController:vc animated:YES completion:nil];
Properties

These are the properties to be set in setProperties method:

  • imageUri (String): Local file path of the face image to be used for face match.
  • completionHook (String) – optional: The url which should be hit with results of face match and other facebook profile details. If this is set to nil or is an empty String, the results will be returned in the completion handler instead.
  • appId,appKey (String): Given by HyperVerge
  • completionHandler: This is to be a closure of type error:NSError?, result:[String:AnyObject]?) -> Void. It is called when the facebook login + HyperVerge server call is successful or when an error has occured in either of the steps. The values of error and result received by the closure determine whether the call was a success or failure.
    • error: If the capture is successful, the error is set to nil. Otherwise, it is an NSError object with following information
      • code: Error code stating the type of error. (discussed later)
      • userInfo: A dictionary of type [String:Any].
        • The key NSLocalizedDescriptionKey has the error description.
    • result: If the capture failed, this is set to nil. Otherwise, it is of type [String:AnyObject].
      If the completionHook is set, this dictionary would be empty. Otherwise it is a dictionary containing the results of face match, first facebook image upload and other profile details.
Result structure:

The result dictionary (returned by framework/posted to completion hook) has the following format.

"result": {
    "matchedImage": {
        "timeValidationPassed": <Boolean - digitally qualified profile>,
        "createdTime": <Number - Epoch time of the oldest matched image, exists only when time validation is passed>,
        "id": <String - ID of the oldest matched image, exists only when time validation is passed>,
        "url": <String - URL of the above image>
        },

    "info": {
        "firstImageActivity": <Number - Epoch time of the oldest image uploaded/tagged image of the user>,
        "id": <String, Facebook User ID>,
        "name": <String>,
        "mostCoTaggedUsers": <Array of user objects who have been tagged in photos with this user the most>
        .
        .
        .
        }
    }
}

Depending on the permissions given by the user and information available in the profile, additional fields might be present in the ‘info’ object of the result. Eg: First Name, Last Name, Email ID, Tagged Places, Devices, Location etc.

Dismissing the ViewController:
By default, when the call is successful or when an error occurs anywhere in the process, the ViewController is dismissed and the completionHandler is called.
If you don’t want the ViewController to be dismissed by the framework, add the following line after instantiating the ViewController.

    vc.shouldDismissOnCompletion = false

Error Codes

Descriptions of the error codes returned in the completionHandler are given here.

Error Code Description Explanation Action
1 Input Error Occurs when input provided to the framework is not correct. Check if all the parameters provided are proper and as per the documentation
2 Network Error Occurs when the internet is either non-existant, very patchy or the call is taking too long to complete Check internet and try again.
3 Internal Server Occurs when there is an internal error at the server. Notify HyperVerge
4 Internal SDK Error Occurs when an unexpected error has happened with the framework. Notify HyperVerge
5 Invalid Image Path Occurs when the image path sent to the framework is invalid Validate the imageUri and retry
6 Face Not Found Occurs when no face is found in the image sent to the framework. Make sure the face is present in the frame. Ensure proper lighting and minimal movement of camera or face while capturing.
7 Multiple Faces Found Occurs when multiple faces are found in the image sent to the framework. Try again. Make sure only one face is present in the frame
101 Inadequate FB Permissions Occurs when the user has not provided minimum permissions(user_photos, public_profile) in Facebook login Try Facebook login again
102 Facebook login cancelled by user Occurs when user clicks on the cancel button in the Facebook login page Try again
103 Facebook login failed Occurs when Facebook returns an error Analyze the error message

Latest podspec

{
    "name": "HVLendingUtils",
    "version": "1.0.2",
    "summary": "HVLendingUtils is HyperVerge's proprietary iOS Utilities Framework for banking and financial services industries.",
    "homepage": "https://github.com/hyperverge/lending-utils-ios-sdk",
    "authors": "HyperVerge",
    "platforms": {
        "ios": "9.0"
    },
    "source": {
        "http": "https://github.com/hyperverge/lending-utils-ios-sdk/blob/master/HVLendingUtils.zip?raw=true"
    },
    "ios": {
        "vendored_frameworks": "HVLendingUtils.framework"
    },
    "dependencies": {
        "FacebookLogin": [],
        "FBSDKLoginKit": []
    }
}

Pin It on Pinterest

Share This