Getting started

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

• Xcode version 12 or later (Current latest is 12.4).  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 10 or later.  You can use an existing project, or you may want to use our iOS sample code to get started.  
• Some 3rd party frameworks require Swift, and your project will need to be compiled using Swift 5.
• 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, countryCode 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, MJCS.framework, IDSLiveness.framework and GIDResources.bundle) to the root folder of your project.   
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 four frameworks/bundles (GIDSDK.framework, MJCS.framework, IDSLiveness.framework and GIDResources.bundle) from the file dialog listing.  You can use shift-click or command-click to select multiple bundles at once.  
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.  
   
   
   
   
6. There are three additional frameworks required.  These can be downloaded from the 3rd party links below, and installed manually, or included in your project using a package management system such as CocoaPods or Carthage.  
   The required frameworks are: 
     

     Lottie.framework
     AFNetworking.framework 
     ZipZap.framework
     FLAnimatedImage.framework
   

Set up embedded binaries 

1. Go to (Your Project Target) → General → Frameworks, Libraries, and Embedded Content. 
   
   
2. Add the following required libraries if they are not already included in your project:
   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
       
       
3. The  GIDSDK.framework, MJCS.framework, IDSLiveness.framework, AFNetworking.framework, ZipZap.framework, FLAnimatedImage.framework, Lottie.framework should have been automatically added to the Frameworks, Libraries, and Embedded Content group.  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 Frameworks, Libraries, and Embedded Content group.
   
   
4. Set the seven greenID Mobile related frameworks to be 'Embed & sign':
   
   

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

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. At this stage, due to third party frameworks being used, you may not be able to compile our framework with Bitcode enabled.   If you experience issues with Bitcode, go to (Your Project Target)→ Build Settings and search for "Bitcode", and set it to "No".
   
   
   
   
   
3. Some of the third party frameworks require Swift to run.  If you want to target phones running iOS versions lower than 13, you will need to embed the Swift standard libraries in your build.  
   Go to (Your Project Target)→ Build Settings and search for "Swift", and set "Always Embed Swift Standard Libraries" to "Yes".

Required app permissions 

To build your app using Xcode 11, 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, countryCode, 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.  
   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