iOS UI Customisation (v 2.x)
- Matt Gray (Unlicensed)
- Sharmeen Hussain
- Aubrey Kilian
To customise the native iOS user interface, you will need to change various files inside the GIDresources.bundle, inside the MJCS frameworks, and sometimes in your app.
Where possible, we recommend that you make any changes in your own app, rather than changing the GIDresources.bundle directly. This makes it easier for you to update to later versions of the iOS SDK without losing your local customisations.
Warning: Before you start customising
When you are customising the SDK UI, there is potential for mistakes to be made. If you find that your app is inoperable, we may ask you to revert to the original SDK files as a first step in diagnosing any issues, and to remove any customised UI settings.
Some customisations on iOS SDK require you to open the MJCS frameworks, and change files inside the frameworks. This means that with each new SDK release, you will need to re-apply your customisations. We are working with our third party providers to work out a more maintainable method for these customisations.
We will be able to provide advice on customising the UI in the SDK, but there are limitations to what you can change in the UI.
Note that users may change the font size on their phone. Where possible the workflow will increase or decrease font size as requested by the user. If you customise any text strings, keep in mind that it may be displayed at a different size on some users' phones.
Note that the variables on this page are only some of the more prominent ones available for customising. Always check the files in the GIDresources.bundle for a complete list of customisable variables for wording, colours, and more.
1. Changing the loading screen
The 'Loading' screen will appear throughout the greenID workflow, usually as a cover screen while new parts of the process start or finish. The text may say "Loading" by default, or sometimes "We're uploading your images".
Most of the loading screens are part of the native SDK, and can be modified as below.
Note that some of the loading screens are part of the web view, and as such can be modified using CSS changes. You should make sure your CSS and native changes are consistent.
Loading screen - Fonts and colours
Copy the the GIDsettings.plist file from the GIDResouces.bundle, and place your copy in your own project. Make sure that the new file is included in your build target, so that it gets included in your app build.
Edit the plist file to change the following:
| Key | Used by | Default value | Notes |
|---|---|---|---|
| gid_loadingBackgroundColor | The loading screen background colour | #FFFFFF | Should be an html hex code |
| gid_loadingFontSize | The loading screen font size | 29 | |
gid_loadingFontFamily | The loading screen font family | HelveticaNeue-Thin | You can specify any iOS system font here, or include your own custom font file in your app. See instructions at the bottom of this page in 'More information on iOS customisation. |
| gid_loadingFontColor | The loading screen font colour | #417505 | Colour of the primary text on the loading screen. This includes things such as "Loading" or "We're uploading your photos" on the loading screen |
| gid_loadingSecondaryFontColor | The loading screen secondary font color | #AAAAAA | Colour of the text used on slow network connections to display a percentage of the load or upload completed. |
Loading screen - Loading image
The loading screen image is an animated gif file. If you place a gif file in your app called gid_spinner-grey.gif, the SDK will use that file instead of the default spinner.
| Filename | Used by | Notes |
|---|---|---|
| gid_spinner-grey.gif | This is the spinner that appears on the 'Loading' and 'Uploading' progress screens. | Should be an animated gif file. |
Loading screen - Text values
To change the text values on the loading screens, add these key/values to a Localizable.strings file in your app. If you have not set up a Localizable.strings file before, there is more information at the end of this document. An example localizable.strings file is available on the greenID Mobile release website.
| Key | Used by | Default value |
|---|---|---|
loading_view_title | Most loading screens | Loading |
upload_progress_message | After additional document capture | We\'re uploading your photo. Please wait. |
2. Changing the camera permission messages
When a user first starts the greenID process, their phone will prompt them for permission to use the camera.
If they deny permission, they will see a dialog explaining that the process cannot continue without permission.
The wording on this dialog can be altered by adding key/values into a Localizable.strings file in your app.
An example localizable.strings file is available on the greenID Mobile release website.
Camera permissions messages
| Key | Used by | Default value |
|---|---|---|
camera_access_denied_title | Title of the dialog box | We can't access your camera |
camera_access_denied_message | Message in the dialog box | Completing this process successfully requires that you allow access to the camera on your device via Settings. |
camera_access_denied_button_title | Button text, to take user to the settings app | Go to Settings |
3. Changing the document capture UI
The colours and fonts of the document capture cannot be changed.
The text of the document capture process can be changed by editing a file inside the MJCS.framework.
The 'GBG | IDScan' branding can be removed, by adding a line to your application Info.plist.
Document capture UI
Modifying the MJCS framework file includes the risk that you may accidentally alter other parts of the capture framework. Take care when modifying this file. If your capture tool stops working, you will need to restore to the provided framework files before we can offer any support.
Document capture - Messages, labels, and other text
Text values in the document capture widget can be changed by altering a file inside the MJCS.framework. The file is: MJCS.framework/en.lproj/Localizable.strings. Editing this file will allow you to change the text messaging.
These keys and default values are mostly similar to the Android values, but there may be some subtle differences
| Key | Default string | Used by |
|---|---|---|
MJCS_blur_detected | Blur detected | Overlay when blur detection has been triggered |
MJCS_document_boundary_detected | Keep document within the frame | Overlay when no document border is detected |
MJCS_extraction_confirm_cancel | Cancel | Button label to cancel the capture, if manual capture has been used |
MJCS_extraction_confirm_finish | Finish | Button label to finish the capture, if manual capture has been used |
MJCS_glare_detected | Glare detected | Overlay when glare detection has been triggered |
MJCS_journey_action_front | Please capture your document | Wording at top of screen, when capturing front of a document |
MJCS_journey_action_back | Please capture the back of your document | Wording at top of screen, when capturing back of a document |
MJCS_journey_action_rescan | Please try again | Retry text, if capture did not work |
MJCS_low_resolution_detected | Move your document closer | Overlay if the document is too small to capture |
MJCS_no_rectangle | We were unable to detect your document in the image captured. Please try again. | Error message if the document detection did not find a document, and the user will have to try another capture |
MJCS_progress_action_retry | Retry | Button label to retry capture |
MJCS_progress_unreachable_title | There is a connection issue | Overlay if the server cannot be contacted |
MJCS_progress_upload_message | Please wait a few seconds... | Overlay when uploading capture image to the server |
MJCS_progress_upload_title | Uploading | Heading text when uploading capture image to the server |
| MJCS_journey_action_selfie | Please capture your selfie | Text shown to user at start of selfie capture |
| MJCS_scanning_message | MJCS_scanning_message | Text displayed to guide user during document capture |
Document capture - GBG branding image
To remove any 'GBG' or 'IDScan' branding that appears on the document capture screens, you can add a line in your application's Info.plist file:
Key: IDSWhiteLabelEnabled
Value: YES
To remove the GBG or IDScan branding from the selfie capture, the process is the same. Adding the key to your Info.plist will turn off the branding for both document and selfie screens.
4. Changing the selfie capture UI
The colours and fonts of the selfie capture cannot be changed.
The text of the selfie capture process can be changed by editing a file inside the MJCS.framework.
The 'GBG | IDScan' branding can be removed, by adding a line to your application Info.plist.
Selfie capture UI
Modifying the MJCS.framework file includes the risk that you may accidentally alter other parts of the capture framework. Take care when modifying this file. If your capture tool stops working, you will need to restore to the provided framework files before we can offer any support.
Selfie capture - Messages, labels, and other text
Text values in the document capture widget can be changed by altering a file inside the MJCS.framework. The file is: MJCS.framework/en.lproj/Localizable.strings. Editing this file will allow you to change the text messaging.
These keys and default values are mostly similar to the Android values, but there may be some subtle differences
| Key | Default string | Used by |
|---|---|---|
MJCS_action_liveness_calibrate_up | Move the device slightly up | Initial messaging when the user is about to do the Liveness step, if they have not got their phone upright. See also 'down', 'left', 'right' for similar messages |
| MJCS_action_liveness_calibrate_down | Move the device slightly down | See above |
| MJCS_action_liveness_calibrate_left | Move the device slightly left | See above |
| MJCS_action_liveness_calibrate_right | Move the device slightly right | See above |
| MJCS_action_liveness_calibrate_proceed | Proceed | Shown during liveness step once user's device is in the right position/orientation. |
MJCS_action_liveness_message | Please look straight at the camera and perform the actions presented to you | Initial messaging informing user how to perform Liveness step. |
MJCS_action_liveness_title | Liveness Detection | Heading text for Liveness step |
MJCS_action_liveness_smile | Smile | Text for possible Liveness test |
MJCS_action_liveness_frown | Frown | Text for possible Liveness test |
MJCS_action_liveness_front | Look straight at the camera | Text for possible Liveness test |
MJCS_action_liveness_down | Tilt your face slightly down | Text for possible Liveness test |
MJCS_action_liveness_up | Tilt your face slightly up | Text for possible Liveness test |
MJCS_action_liveness_left | Turn your face slightly left | Text for possible Liveness test |
MJCS_action_liveness_right | Turn your face slightly right | Text for possible Liveness test |
| MJCS_action_liveness_none | No Action | Text for possible Liveness test |
Selfie capture - GBG branding image
To remove the GBG or IDScan branding from the selfie capture, the process is the same as for Document Capture above. Adding the key to your Info.plist will turn off the branding for both document and selfie screens.
5. More information on iOS customisation
Using a custom font family
If you want to use a custom font that is not included with iOS, you can include it in your app as follows:
- Copy the font file into the resources for your app. Make sure it is part of the 'Copy bundle resources' build phase
- Add a key to your Info.plist file called UIAppFonts. ("Fonts provided by application")
- Make this key an array (Xcode may do this automatically for you)
- For each custom font you have, enter the full name of your font file (including the extension) as items to the UIAppFonts array
- Save Info.plist
You can then use these custom fonts in the gid_loadingFontFamily setting.
Steps to integrate the GIDResources bundle into a calling application
If you have not previously integrated the GIDResources.bundle into your project, follow these steps.
- Copy the GIDResources bundle to the Root folder of the project
- Go to (Your Project Target) → Build Phases → Copy Bundle Resources → Click on the + Button → Select Add Other. Select the GIDResources Bundle from window.
- That's it!
(Figure a) Select Add Other:
(Figure b) Select the GIDResources Bundle from window:
(Figure c) Copy the items if needed:
(Figure d) The newly added GIDResources will appear in the Xcode project navigator and in the copy bundle resources:
Setting up a Localizable.strings file
A strings file named Localizable must be created inside of the parent application. This is done by using these steps:
- Go to File > New > File. Choose Strings File unders the Resource subsection as shown below:
- Click Next, name the file Localizable.strings, then click Save.
Now that you’ve created the Localizable.strings file, you need to add all of the text key value pairs that you want to configure in the Localizable.strings file. You need to follow a specific, but fairly simple, format like this: "KEY" = "VALUE" .
- Make sure that you make the file 'Localized' in Xcode, as shown below. This will move it into a language folder, and make it work with the capture widgets in the greenID Mobile SDK:
Note: Localizable.strings is the default filename iOS uses for localized text. Resist the urge to name the file something else, otherwise you will have to type the name of your .strings file every time you reference a localized string.
Not all the key value pairs need to be declared in the Localizable.strings file. Only the key value pairs that need to be overridden should be configured. If a key value pair is not present in the newly created Localizable.strings file, the default value for the key specified will be initialised.
Home | greenID API | greenID Web | greenID Mobile | greenID Business | greenID Additional Services | Notification of Verification | Admin Panel Guide
If you can't find what you need here, email us at customer.support@gbgplc.com or log a ticket via our portal
On this page
greenID Mobile A-Z