Upgrading your iOS SDK

The following information is for customers upgrading from a previous versions of the iOS SDK to more recent versions.

Upgrading from version 1.5 to 1.6.0

We have amended the original callback method:

Objective-C

   - (void)mainViewController:(nonnull GIDMainViewController *)mainViewController 
didCompleteProcessWithPayload:(nullable NSDictionary *)payload 
                   resultCode:(GIDResultCode)resultcode;

Swift

	public func mainViewController(_ mainViewController: GIDMainViewController, 
				  didCompleteProcessWithPayload payload: [AnyHashable : Any]?, 
											 resultCode: GIDResultCode)

To now look like:

Objective-C

   - (void)mainViewController:(nonnull GIDMainViewController *)mainViewController 
didCompleteProcessWithPayload:(nullable NSDictionary *)payload 
                   resultCode:(GIDResultCode)resultCode 
                        error:(nullable id <GIDErrorProtocol>)error;

Swift

	public func mainViewController(_ mainViewController: GIDMainViewController, 
  				  didCompleteProcessWithPayload payload: [AnyHashable : Any]?, 
											 resultCode: GIDResultCode, 
												  error: GIDErrorProtocol?)

We have added an error parameter. It is an object that conforms to the GIDErrorProtocol protocol. This object contains a few properties/functions to help identify exactly why, what, how an error occurred.

Property	Definition
underlyingError	The actual underlying NSError object of the error that occurred.
gidErrorCode	A type part of the ‘GIDErrorCode’ enum.
gidErrorLocalizedFailureReason	The reason why the error occurred.
gidErrorRecoverySuggestionString	A suggestion on how to get past the error or how to even resolve it.
gidErrorShortenedDescription	A short human readable summary of the error that occurred.

The error object will have an error code, error.gidErrorCode, which will be one of the following:

GIDErrorCode - Objective-C	GIDErrorCode - Swift	Meaning
GIDErrorCodeNetwork	GIDErrorCode.network	No network connection is available, or the active network connection is no longer accessible
GIDErrorCodeOCR	GIDErrorCode.OCR	Something went wrong when trying to extract text from an ID card.
GIDErrorCodeAID	GIDErrorCode.AID	Something went wrong when trying to authenticate the ID. This will usually be a backend server problem.
GIDErrorCodeSnap	GIDErrorCode.snap	Something went wrong when trying to capture a document using the device camera.
GIDErrorCodeWebApp	GIDErrorCode.webApp	The greenID web process returned an error. This will usually be a backend server problem.
GIDErrorCodeUserInactivity	GIDErrorCode.UserInactivity	There was no user activity within the application interface.

While the error description, failure reason and recovery suggestion may be presented to your user, we would suggest that your app rewrites any error strings to be consistent with your branding and language, rather than using the GIDError descriptions verbatim.

We have also removed the catFishMerchantKey, catFishSecretKey and catFishURL properties/functions from the GIDData object. This is now handled automatically by the GIDSDK.

Upgrading from version 1.6.0 or higher to version 1.6.5

We have updated the frameworks we use within the greenID SDK. These updated frameworks need to be added to your project as well. Please refer to the section Adding the greenID SDK to your Project for more information on how to add these frameworks to your project.

Upgrading from version 1.6.5 or higher to version 1.9.1

Version 1.9.1 of the greenID SDK will still work normally and as expected, without needing to make any changes on how your app integrates with the SDK, although we did make a change to the API that is optional for your app to adopt.

On the GIDSDKConstantsAndEnums.h file we have added 3 new NSString constants. These 3 constants can be used as a key (along with a NSString value) to pass into the additionalParameters dictionary when setting up the GIDData object. These constants have the following effect:

Constant	Effect
kGIDSDKSelfieScanEyeThreshold	This value needs to be a value within the range of 0-100. If the value is outside of this range, the value will be ignored. This value controls the vote count for the Selfie scan tool. The higher the vote count, the more robust the Selfie scan tool will turn out to be.
kGIDSKDSelfieScanNumberOfBlinks	This value needs to be a value greater or equal to 1. The value will be ignored if the condition is not met. This value controls the number of blinks to detect for auto capture.
kGIDSDKSelfieScanResetTimeout	This value needs to be a value greater or equal to 1. If the value is equal to or less than 0, the `greenID iOS SDK` will set the selfie capture mode to `CFAManualCapture from the default CFASemi_Auto capture mode.` This value controls the timeout for resetting the blink count, if the desired blinks are not reached.

Please note: The values for these keys (when passed into the additionalParameters dictionary) needs to be NSString values. The SDK will ignore and fall back to the SDK default for these values if they are not of type NSString.

Upgrading from version 1.9.1 or higher to version 1.11.0

Version 1.11.0 of the will work as expected without having to adopt any changes.

There has been additions to the following:

An optional .Localizable.strings file can be created in any parent application that adopts the greenId iOS 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:

Document Configuration for iOS SDK Localizable.strings file

A additional component has been added to the greenID iOS SDK to allow a parent app to monitor user activity in the form of a timer. A detailed GIDErrorCodeUserInactivity error message and a GIDResultCodeUserInactivity result code is sent back to the parent application when the condition that there has been no user activity for a default period of more than 300 seconds is met.

This default can be configured by the parent application by using the following key as an additional parameter. On the GIDSDKConstantsAndEnums.h file we have added one new NSString constants. This constant can be used as a key (along with a NSString value) to pass into the additionalParameters dictionary when setting up the GIDData object. This constant have the following effect:

Constant	Effect
kGIDSDKMaxIdleTimeSeconds	This value controls the number of seconds for setting the inactivity timer. The default is 300 seconds.

Upgrading from version 1.11.0 or higher to version 1.12.0

Version 1.12.0 of the greenId iOS SDK will not work as expected and there will be a requirement to update your respective application in order to accommodate the latest changes within the SDK.

Framework changes:

Version 1.12.0 requires updates to your project, to remove old frameworks and add new frameworks.

Remove the following two frameworks from your project: IDMetrics.framework MobileFlow.framework
Add the following two frameworks as embedded binaries: IDMetricsDocumentCapture.framework IDMetricsSelfieCapture.framework
Add the following bundle to your project: GIDResources.bundle - it should automatically go into the Copy Bundle Resources build phase.

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

IOS GreenID SDK: GIDResources.bundle Configuration.

Additional errors:

A detailed GIDErrorCodeResourceBundle error message and a GIDResultCodeResourceBundle result code is sent back to the parent application when the condition that there is a missing or no resource bundle is met.

Configuration changes:

The configuration for the kGIDSDKSelfieScanResetTimeout parameter has changed to meet the following condition:

If the value is equal to or less than 0, the greenID iOS SDK will set the selfie capture mode to manual capture from the default semi-auto capture mode.

Deprecations:

This version has removed the callback method that was deprecated in version 1.6.0. If you are still using the callback method from version 1.5 or earlier, it will no longer be called, and your app will not receive any notification when the greenID SDK hands off an error or verification result. The correct delegate method to use is:

 - (void)mainViewController:(nonnull GIDMainViewController *)mainViewController 
didCompleteProcessWithPayload:(nullable NSDictionary *)payload 
                   resultCode:(GIDResultCode)resultCode 
                        error:(nullable id <GIDErrorProtocol>)error;

App permissions:

Version 1.12.0 requires additional permissions from your app. You should add a NSLocationWhenInUseUsageDescription key to your app's Info.plist file.

Upgrading from version 1.12.0 or lower to version 1.13.0

This version includes a new optional parameter. The documentCaptureResetTimeout parameter controls the amount of seconds after which the document scanning process will failover to manual capture mode. this allows the user to frame the document themselves, and manually tap the capture button.

Constant	Effect
kDefaultDocumentCaptureResetTimeOut	This value controls the amount of seconds after which the document scanning process will failover to manual capture mode, allowing the user to frame the document themselves, and manually tap the capture button.

Upgrading from version 1.13.0 or lower to version 1.13.8

This version includes three new optional parameters, for setting the document capture timeouts for different document types: documentCaptureLicenceResetTimeout, documentCapturePassportResetTimeout, and documentCaptureGreenIDResetTimeout
The mode parameter is now compulsory. The SDK will not start if the mode parameter is not set.

Upgrading from version 1.13.8 or lower to version 1.14.1

This version has two new images (in 3 sizes each) included in the GIDResources.bundle. You can update the GIDResources.bundle by replacing it with the new bundle provided, or if you have made customisations in your bundle, manually copy the crossIcon.png and tickIcon.png files into your copy of GIDResources.bundle.

Upgrading from version 1.14.1 or lower to version 1.15.0

This version has a new required framework to include: iFaceRec.framework. Refer to the integration instructions for more details.
The Always embed Swift standard libraries build setting for your app should be updated to 'Yes'
This version requires Xcode 9 to build. Xcode 8 will not work with this version.
This version will only run on iOS 10 and 11 devices, due to one of our third party frameworks. We will be remedying this in a future release.

Upgrading from version 1.15.0 or lower to version 1.16.0

The Always embed Swift standard libraries build setting for your app can now be set to 'No' if you don't use Swift. We have removed our Swift dependency.
This version now works with Xcode 8 and 9.
This version will only run on iOS 9, 10 and 11 devices, due to one of our third party frameworks.
New versions of the Document capture, selfie capture and iFaceRec frameworks are included, be sure to copy the new frameworks into your project.
If you pass in incorrect startup parameters, the SDK will immediately handoff back to your app, with an error object that contains information on how to fix the problem.
If you have a custom background colour using custom CSS, make sure to set a matching background colour in the GID Resources bundle. This will avoid a white strip at the top of some screens in landscape orientation.

Upgrading from version 1.16.0 or lower to version 1.17.0

This version will now run on iOS 8 to iOS 11.
A new version of the iFaceRec framework is included, be sure to copy the new framework into your project.
This version has updated images (in 3 sizes each) included in the GIDResources.bundle. You can update the GIDResources.bundle by replacing it with the new bundle provided, or if you have made customisations in your bundle, manually copy the crossIcon.png and tickIcon.png files into your copy of GIDResources.bundle.

Upgrading from version 1.17.0 to version 1.17.1

A new version of the Document capture and selfie capture framework is included, be sure to copy the new frameworks into your project.
Note that iOS 8 is no longer supported from this build onwards.
There is an additional framework called MicroBlink.framework, which you will need to copy into your project, link and embed like the other frameworks.
There is a missing piece of text in the document capture tool - to fix this, you will need to add the following to your Localized.strings file:

"second_overlay_licence_text_line1" = "";
"second_overlay_passport_landscape_text_line1" = "";

Upgrading from version 1.17.1 to version 1.18.0

No configuration changes required, other than copying in the new GIDSDK framework.

Upgrading from version 1.18.0 to version 1.19.0

New framework has been provided for iFaceRec. Make sure you copy it to your project.
New logging/analytics methods have been provided. You can optionally use these to receive logging from the SDK. See the integration documentation for more details.

The use of GIDData is now deprecated. You can continue to use it to start the GIDSDK, but the compiler will warn you to upgrade to the new initialisation code.
If you want to upgrade to the new initialisation code, do the following:

Put the configuration parameters into a dictionary of NSString objects.
Change GIDMainViewController to use initWithConfig: rather than init

Sample startup code:

	NSDictionary *config = @{
                             @"apiCode" : @"", // TODO: Insert your API Code here
                             @"accountId" : @"", // TODO: Insert your accountID here
                             @"baseUrl" : @"https://simpleui-test-au.vixverify.com",
                             @"mode" : @"onboarding",
                             };
    
	GIDMainViewController *main = [[GIDMainViewController alloc] initWithConfig:config];

Upgrading from version 1.19.0 to version 1.20.0

Copy in all provided framework files. Changes have been made in GIDSDK, DocumentCapture and SelfieCapture frameworks.
MicroBlink.framework is now not required by GIDSDK. Remove it from your project if you had included it as part of a previous GIDSDK release.
"second_overlay_licence_text_line1" is no longer required in your Localized.strings file. You can remove it if you wish.

Upgrading from version 1.20.0 to version 1.21.0

Copy in all provided framework files. Changes have been made to the GIDSDK framework.
Add some code to your delegate method to handle the new handoff state: GIDResultCodeNetworkSecurityError. This error will occur if the phone cannot contact the server at the start of the process, to check the SSL certificate, or if the network the the phone is on is rewriting the SSL certificates.

Upgrading from version 1.21.0 to version 1.22.0

Copy in all provided framework files. Changes have been made to the GIDSDK framework.
Review the integration information about UI customisation. More options and details are now available for customising the look of the workflow.

Upgrading from version 1.22.0 to version 1.23.0

Copy in all provided framework files. Changes have been made to the GIDSDK framework.
Optionally add in the new prestartCheckForError: method before you push the GIDSDK object to your navigation stack. See the sample code for an example. Doing this check will make sure that the SDK is ready for navigation, and can improve your user experience - avoiding pushing then immediately popping the SDK if it could not start up.