Getting started

There are several things you will need in order to integrate the greenID SDK into your code.  

• Xcode version 8 or 9.  Xcode can be downloaded for free from the Apple App Store.  You will require an Apple ID to download Xcode.  
• A copy of the greenID SDK zip file for iOS.  This contains the greenID framework, as well as several other framework files that are required to make greenID work
• A project in Xcode, using Objective-C or Swift, targeting iOS 9 or later.  You can use an existing project, or you may want to use our iOS sample code to get started.  
• Several account settings from the greenID Mobile team.  You will not be able to use the greenID SDK without the necessary account information.  At a minimum, accountID, apiCode, mode, and baseURL will be required.  Other configuration variables may be required as you do further integration and testing. 
• To test your code, you will need to run it on a physical device.  You will need an Apple Developer account to load your app onto a physical device.   

Adding the greenID SDK to your project

Add frameworks and bundles to your project

1. Uncompress the greenID SDK zip file.
2. In the Finder, copy the framework bundles (GIDSDK.framework, IDMetricsDocumentCapture.framework, IDMetricsSelfieCapture.framework, iFaceRec.framework and GIDResources.bundle) to the root folder of your project.  Note for SDK 1.17.1 - SDK 1.19.0:  Also, copy MicroBlink.framework.  
3. Open your project in Xcode. Expand your project in the left pane. There should be a Frameworks group in you project directory in Xcode. Right click on the Frameworks group and select the Add files to "(Your project name)"... option from the menu.
   
   
   
   
4. Select the five frameworks/bundles (GIDSDK.framework, IDMetricsDocumentCapture.framework, IDMetricsSelfieCapture.framework, iFaceRec.framework and GIDResources.bundle) from the file dialog listing.  You can use shift-click or command-click to select multiple bundles at once.  Note for SDK 1.17.1 - SDK 1.19.0:  Also, select MicroBlink.framework.
5. Click on the Options button at the bottom of the dialog. Select the project targets that the bundles should be added to. Also ensure the Copy items if needed and the Create groups options are selected.   When the five frameworks/bundles have been selected, and the options have been set, click the Add button.  The five items should now show in the Frameworks folder in your Xcode project.  
   
   

Set up embedded binaries 

1. Go to (Your Project Target) → General → Click on the + Button under the Embedded Binaries group
   
   
   
   
2. Search for and select 4 frameworks - GIDSDK.framework, IDMetricsDocumentCapture.framework, IDMetricsSelfieCapture.framework and iFaceRec.framework in the window that appears.  You can use shift-click or command-click to select multiple frameworks to add in one step.  Note for SDK 1.17.1 - SDK 1.19.0:  Also, select MicroBlink.framework.  
3. Click the Add button.  The four frameworks should now show under the Embedded Binaries section of your settings.  
   
   
   
   
   
   
   

Add required system frameworks and libraries

(If you are using the sample project as a starting point, this section should have been done for you already.)

1. Go to (Your Project Target) → General → Linked Frameworks and Libraries → Click on the + Button. 
   
   
   
   
2. Add the following required libraries from the list presented.  Remember that you can select multiple items using shift-click or command-click.    
   1. AudioToolbox.framework
   2. AVFoundation.framework
   3. CoreGraphics.framework
   4. CoreMedia.framework
   5. CoreVideo.framework
   6. MobileCoreServices.framework
   7. OpenGLES.framework
   8. QuartzCore.framework
   9. Security.framework
   10. ImageIO.framework
   11. Foundation.framework
   12. UIKit.framework
   13. libstdc++.6.tbd  For Xcode 10 onwards, remove the reference to the libstdc++ library
       
       
       
       
3. The GIDSDK.framework, IDMetricsDocumentCapture.framework,IDMetricsSelfieCapture.framework and iFaceRec.framework should have been automatically added to the Linked Frameworks and Libraries group as well.  If not, add them manually.  The easiest way to do this is to drag the framework file(s) from the project list on the left of screen, and drop it on the Linked Frameworks and Libraries group.
   
   
   
   
4. Sometimes, frameworks will appear twice to the the Linked Frameworks and Libraries group.  If that has happened, click on one of the duplicate entries and delete it.  

Customise resources and localised strings (Optional) 

1. The greenID iOS SDK zip file also includes a bundle archive (GIDResources.bundle) which contains greenID SDK image resources used within the SDK.  This bundle should have been added to your project in the steps above.  You can confirm that the bundle is being included in your project by checking  (Your Project Target) → Build Phases → Copy Bundle Resources

   
   
   

   
   

   
   Optional:  You can customise any of the images in the GIDResources.bundle to match your branding.  A complete guide on the process that must be followed can be obtained here: 

   • iOS UI customisation
     
     

2. Optional: A Localizable.strings file can be created in any parent application that adopts the greenId SDK. This enables the configuration of the default text strings in the iOS SDK.

   A complete guide on the process that must be followed can be obtained here: 

   • iOS UI customisation
     
     Note for SDK 1.17.1 - SDK 1.19.0:  You will need to create entries in your Localizable.strings file for "second_overlay_licence_text_line1" and  "second_overlay_passport_landscape_text_line1"
     
     Without these lines, the document capture tool shows incorrect text after the capture.  This has been fixed in SDK 1.20.0.     

Required project settings

1. Go to (Your Project Target)→ General → Deployment Info.  Make sure that the Device Orientation supports at least Portrait, Landscape Left and Landscape Right.
   (If you need to restrict parts of your app to portrait mode only, you can do this using - (UIInterfaceOrientationMask)supportedInterfaceOrientations in your view controllers, rather than restricting the whole app)
   
   
   
   
2. Add the following linker flags to your project under “Other Linker Flags” in Build Settings.  Go to (Your Project Target)→ Build Settings and search for "Other Linker Flags", then add the following:
   
   1. -lstdc++
   2. -lc++





3. At this stage, due to third party frameworks being used, we can not compile our framework with bitcode enabled.   Go to (Your Project Target)→ Build Settings and search for "Bitcode", and set it to "No".
   
   
   
   
   

Required app permissions 

To build your app using Xcode 8 or 9, you need to provide privacy permissions in your Info.plist file.  If your app does not include these values, it might crash as soon as it tries to start the greenID workflow, or key functionality such as the camera being able to take photos may not work.  

The app may also be rejected by Apple's review process if these values are not in your Info.plist.  

1. Open your Info.plist file in Xcode
   
   
   
   
2. Add entries for the following.  You can use the raw key or the longer description key when entering these items:

Note about camera permissions:  If a user of your app declines the camera privacy permission, greenID will not be able to photograph the user or their ID.  If the user later changes the camera permission using the iOS Settings app, the operating system will force a restart of your app if it is running.  This is standard behaviour for iOS.  You might choose to implement an application delegate method to handle such a restart, and take the user back to the start of the greenID process in your app.  

Using the greenID SDK with simulator builds and automated testing

From GIDSDK version 1.22.0 onwards, we also provide a simulator architecture version of the SDK and frameworks.  If you need to test minimal functionality on a simulator, rather than physical device, please refer to Using the greenID simulator-enabled iOS frameworks. 

Using the SDK 

Once greenID SDK has been added to your project using the above steps, you can start using it in your code.  

1. Import <GIDSDK/GIDSDK.h> (objective-c) or import GIDSDK (Swift) into your view controller.

2. Make your class conform to the GIDDelegate protocol to receive the data payload and result of the interaction with the greenID SDK.

3. Set the relevant configuration parameters (see SDK Configuration Variables) in a dictionary.  As a minimum,  accountId, apiCode, mode and baseUrl will be required for instantiating the Framework.  The other values will have sensible defaults assigned by the greenID platform.
4. Create an instance of the greenID SDK GIDMainViewController 
5. Push GIDMainViewController to your navigation controller.  
   As of version 1.23.0, you can optionally use the prestartCheckForError: method first, to make sure the SDK is ready to be pushed to your navigation controller.  
6. Add greenID SDK delegate methods to receive the data payload and responses.
7. When your app is finished with the greenID workflow, make sure you remove it from the navigation controller using a

   popViewControllerAnimated: or setViewControllers: call.  This is important, as removing GIDMainViewController from the navigation stack will deallocate all of the memory associated with the greenID process. 

If you look at the iOS sample code, you will see these steps in the ViewController.h and ViewController.m file (or ViewController.swift file). 

Querying Details of the Verification Process

The verificationToken is passed to the mainViewController:didCompleteProcessWithPayload:resultCode:error: method.
Please see Querying the Outcome of the Verification Process for more information.

Result codes of the verification process (GIDResultCode)

GIDResultCodeNetworkSecurityError

GIDResultCode.networkSecurityError

GIDResultCodeUserInactivity

GIDResultCode.userInactivity

GIDResultCodeResourceBundle

GIDResultCode.resourceBundle

The verificationState as well as the verificationToken can be retrieved from the didCompleteProcessWithPayload delegate method. These verification variables are returned with the payload dictionary. Note that the verification variables will only be returned if the resultCode is of type GIDResultCodeSuccess. The verification values would look something like:

{
    verificationState = "STATE";
    verificationToken = "TOKEN";
}

If the result code is either GIDResultCodeError/GIDResultCode.error or GIDResultCodeNoNetwork/GIDResultCode.noNetwork, your app is responsible for informing the user of the error.  From SDK 1.6.0 onwards, a GIDErrorProtocol object is passed back that you can query to get an idea of what went wrong.

Getting logging and analytics from the SDK 

The SDK can pass log events, including some events that can be used for analytics in your app.  This is optional - if you don't want your app to receive log messages, then you don't need to implement this code. 

Note that if you implement the log delegate, the SDK will stop logging most messages to the standard iOS console, as it will be sending them to your delegate function instead.  

To get logging messages:

• First set up a GIDLoggerDelegate class that will handle the log messages.  This can be the same class that starts the GreenID SDK.
• Next, set the log level that the SDK will use.  To receive all events, including analytics, use GIDLogLevelUI.  If you don't set a level, the default is GIDLogLevelInfo, which is a subset of the logging events.  
• Tell the SDK which class is acting as the GIDLoggerDelegate
• Finally, implement the delegate class that will receive the log messages - sdkDidLogLevel: levelCode: analyticsCode: source: message:

The sample code includes this setup code and an example delegate method.

Sample Code for Objective-C and Swift 

Some sample projects, with code for Objective-C and Swift are available.

The sample projects require you to add the latest greenID SDK frameworks and bundles, and add your configuration parameters to the sample code.  They will then be able to build and run the greenID Mobile process on a physical device.  

Upgrading greenID SDK from a previous version

To upgrade your version of the greenID SDK to a newer version, please refer to the release notes, and also to the Upgrading your iOS greenID SDK page.  

These instructions are current as of greenID SDK 1.33.0