iOS UI Customisation
- Former user (Deleted)
- Sharmeen Hussain
- Aubrey Kilian
These instructions are for v 1.x of greenID Mobile iOS SDK. For the latest 2.x versions, please refer to the new instructions.
To customise the native iOS user interface, you will need to change various files inside the GIDresources.bundle, inside the IDMetrics 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 IDMetrics 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.
SDK version 1.21.0 introduced new capabilities to use customisations in your app, rather than requiring changes inside the GIDResources.bundle. Making changes in your app is the preferred method where available.
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
From version 1.13.8, the GIDResources bundle includes a settings file called GIDsettings.plist. This file can be used to configure the colours and font used on the 'Loading' and 'Uploading' progress screens.
From version 1.21.0, you can include a customised copy of the GIDsettings.plist file in your own app. Rather than editing the file inside the GIDResouces.bundle, you can put a copy in your own app, and the SDK will use values in that file instead of the defaults. Copy the default file from the 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. The default image is provided in the GIDResources.bundle. To change this images in your app, replace it with an image of the same name, and rebuild your project.
From version 1.21.0, you can alternatively add the images directly in your own app project - note that the names are slightly different, to avoid name clashes with any other images you may use in your app. Make sure that images are added to your project target, so that they will be included when you build your app. This is the preferred method, so that your changes do not get overwritten with a new SDK release.
| Bundle Filename | App Filename (from v.1.21.0) | Used by | Notes |
|---|---|---|---|
| spinner-grey.gif | 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, fonts and text of the document capture process can be changed by placing values into two files in your app:
The Localizable.strings file, and the Document.json file.
Document capture UI
Document capture - colours, fonts, buttons
The colours and fonts of the document capture tool can be modified in a file called Document.json. This file is located inside the IDMetricsDocumentCapture.framework.
This file will allow you to change the fonts and colours. To change the corresponding text, see the section below.
Note that the colours are in R-G-B-Alpha format.
If you enter invalid colours or fonts, the capture tool will ignore that and use default values.
If your json file is malformed, the whole file will be ignored, and default values will be used for all items.
Modifying this 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.
The following customisation options are available in the file. Some options are not used in a normal greenID mobile workflow and will not be seen in your UI, so they have not been mentioned in this table.
| Key | Used by | Options | Notes |
|---|---|---|---|
icon_got_it | The button on the introduction screen, to start the capture | Font, text size, text colour, background colour | |
icon_close | The image used to cancel the capture | Border appearance for the button | Do not change the icon_name. |
icon_camera | The image used for the manual capture button | Border appearance for the button | Only appears for manual capture. Do not change the icon_name. |
icon_help | The image used for the 'help' button | Border appearance for the button | Do not change the icon_name. |
instruction_overlay | The background and text of the introduction screen | Font, text size, text colour, background colour | |
indicators | The red 'Glare', 'No face', 'Focus' button colours | Font, text size, text colour, background colour | |
| live_overlay | The dialogs that pop up during the capture - for example "Hold steady - Taking 2 photos" | Font, text size, text colour, background colour | |
tooltip | The 'Having some trouble?' text that shows before manual capture | Font, text size, text colour, background colour | Only appears for manual capture |
actionbar | The colour for the words 'Auto capture' | Font, text size, text colour, background colour | Only appears in auto capture |
brackets | The colour of the 4 brackets surrounding the document to be captured. | Colour - can be set for when a document is visible or not | Only changes colour when in auto capture mode |
Document capture - Messages, labels, and other text
Text values in the document capture widget can be changed by including values in a Localizable.strings file in your app. Adding the following key/values will change the following messages.
These keys and default values are mostly similar to the Android values, but there are some subtle differences - e.g. the 'second_overlay' keys for 'text_line1' on Android is 'text_line2' on iOS.
If you customise any of these settings, you may find that you need to explicitly set second_overlay_licence_text_line1, second_overlay_passport_landscape_text_line1 and second_overlay_greenId_text_line1 to empty strings in your Localized.strings file. This is to work around an issue in the third party capture widget that we use. If you do not set these strings, there may be extra text shown by mistake on the dialog box during capture.
Due to the implementation of the third party framework that does the capture, you will have to make sure your Localizable.strings file is a proper 'localized' file in Xcode. The name of the file is not enough, it will have to be localised for a language, which will put it inside a directory named 'en.lproj' or something similar.
If your strings file is not properly localised, your settings may be ignored.
An example localizable.strings file that contains some of these keys is available on the greenID Mobile release website.
| Key | Default string | Used by |
|---|---|---|
first_overlay_licence_flash_front_text_line1 | Align the\nDOCUMENT FRONT\ninside the brackets. | Instructions at start of licence front capture |
first_overlay_licence_flash_front_text_line3 | HOLD STEADY FOR 2 PHOTOS | Instructions at start of licence front capture |
first_overlay_licence_flash_back_text_line1 | Align the\nDOCUMENT BACK\ninside the brackets. | Instructions at start of licence back capture |
first_overlay_licence_flash_back_text_line3 | HOLD STEADY FOR 2 PHOTOS | Instructions at start of licence back capture |
second_overlay_licence_text_line1 | Dialog box that covers screen when the camera is capturing the licence flash image | |
second_overlay_licence_text_line2 | HOLD STEADY | Dialog box that covers screen when the camera is capturing the licence flash image |
second_overlay_licence_text_line3 | Taking 2 photos | Dialog box that covers screen when the camera is capturing the licence flash image |
first_overlay_passport_landscape_flash_text_line1 | Align the\nPASSPORT PHOTO PAGE\ninside the brackets | Instructions at the start of a passport capture |
first_overlay_passport_landscape_flash_text_line3 | HOLD STEADY FOR 2 PHOTOS | Instructions at the start of a passport capture |
second_overlay_passport_landscape_text_line1 | Dialog box that covers screen when the camera is capturing the passport flash image | |
second_overlay_passport_landscape_text_line2 | HOLD STEADY | Dialog box that covers screen when the camera is capturing the passport flash image |
second_overlay_passport_landscape_text_line2 | Taking 2 photos | Dialog box that covers screen when the camera is capturing the passport flash image |
first_overlay_greenId_flash_text_line1 | Align the\nPHOTO PAGE\ninside the brackets | Instructions at the start of a South African Booklet capture |
first_overlay_greenId_flash_text_line3 | HOLD STEADY FOR 2 PHOTOS | Instructions at the start of a South African Booklet capture |
second_overlay_greenId_text_line1 | Dialog box that covers screen when the camera is capturing the South African Booklet flash image | |
second_overlay_greenId_text_line2 | HOLD STEADY | Dialog box that covers screen when the camera is capturing the South African Booklet flash image |
second_overlay_greenId_text_line3 | Taking 2 photos | Dialog box that covers screen when the camera is capturing the South African Booklet flash image |
indicator_focus | Not in focus | Warning text during capture |
indicator_glare | Glare detected | Warning text during capture |
indicator_face | No face found | Warning text during capture |
indicator_movecloser | Move Closer. | Warning text during capture |
tooltip_doc_manual_capture_heading | Having some trouble? | Text in dialog that shows just before manual capture |
tooltip_doc_manual_capture | Take the photo using\nthe capture button | Text in dialog that shows just before manual capture |
alert_doc_cancel_message | Are you sure you want to exit? | Cancel dialog text |
alert_doc_cancel_title | Cancel Capture | Cancel dialog heading |
alert_doc_positive_button | Yes, I\'m sure | Cancel dialog button text - to cancel |
alert_doc_negative_button | No, go back | Cancel dialog button text - to continue capture |
doc_capture_label | AUTO\nCAPTURE | Text shown on the side of screen, when auto capture is being attempted |
doc_overlay_gotit_button | Got it! | Text on the button on the introduction screen |
Document capture reference images
The following images show labels for the keys in the Localizable.strings and Document.json files. The Localizable.strings keys are shown in blue, and the Document.json keys are shown in yellow.
4. Changing the document review screen UI
The document review screen appears immediately after a document capture.
Some parts of this screen can be customised, starting with the 1.33.0 SDK release.
Document review screen UI
Review screens - colours
From version 1.33.0, you can add the following to your copy of GIDsettings.plist
Edit the plist file to change the following:
| Key | Default | Used by |
|---|---|---|
| gid_id_review_screen_background | #6B6B6B | The background colour of the review screen |
| gid_id_review_screen_text_please_confirm | #FFFFFF | The text colour of the first line of text ("Please confirm") |
| gid_id_review_screen_text_color | #D6D6D6 | The text colour of the remaining text on the page |
Remember to check any colour changes that you make on this screen to ensure that they pass contrast checks for accessibility.
Review screens - Messages and other text
From version 1.33.0, you can add the following to your copy of Localizable.strings file. You can use basic HTML to style the text.
Edit the strings file to change the following:
| Key | Default | Used by |
|---|---|---|
| gid_id_review_screen_confirm_text | Please <b>confirm:</b> | The first line of text |
| gid_id_review_screen_document_in_focus_confirm_text | It\'s <b>in focus</b> | The 3rd line of text. |
| gid_id_review_screen_document_no_glare_confirm_text | There\'s <b>enough</b> <b>light</b> but <b>no glare</b> | The 4th line of text. |
The 2nd line of text is created programatically, and cannot be changed by the client.
Review screens - Voiceover text
If you change the messaging on the review screen, you should also change the Voiceover accessibility messaging to match.
In the Localizable.strings file, change the following:
| Key | Default | Used by |
|---|---|---|
| doc_review_info_accessibility_alert_title | Please confirm: | Text read out by screen reader for the review screens |
| doc_review_info_accessibility_alert_message | The full photo page is visible\n\nIt's in focus\n\nThere's enough light but no glare | Text read out by screen reader for the review screens |
5. Changing the selfie capture UI
The colours, fonts and text of the selfie capture process can be changed by placing values into two files in your app: The Localizable.strings file, and the Selfie.json file.
Selfie capture UI
Selfie capture - colours, fonts
The colours and fonts of the document capture tool can be modified in a file called Selfie.json. This file is located inside the IDMetricsSelfieCapture.framework.
This file will allow you to change the fonts and colours. To change the corresponding text, see the section below.
Note that the colours are in R-G-B-Alpha format.
If you enter invalid colours or fonts, the capture tool will ignore that and use default values.
If your json file is malformed, the whole file will be ignored, and default values will be used for all items.
Modifying this 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.
The following customisation options are available in the file. Some options are not used in a normal greenID mobile workflow and will not be seen in your UI, so they have not been mentioned in this table.
| Key | Used by | Options | Notes |
|---|---|---|---|
retake | The button for re-attempting the selfie capture | Font, text size, text colour, background colour | Only appears for manual capture |
| this_is_me (key changed to 'accept' in release 1.35) | The button for approving the selfie | Font, text size, text colour, background colour | Only appears for manual capture |
icon_help | The image used for the 'help' button | Border appearance for the button | Do not change the icon_name. |
icon_camera | The image used for the manual capture button | Border appearance for the button | Only appears for manual capture. Do not change the icon_name. |
icon_close | The image used to cancel the capture | Border appearance for the button | Do not change the icon_name. |
icon_got_it | The button on the introduction screen, to start the capture | Font, text size, text colour, background colour | |
instruction_overlay | The background and text of the introduction screen | Font, text size, text colour, background colour | |
| live_overlay | The dialogs that pop up during the capture - for example "Put your head in the centre" | Font, text size, text colour, background colour | |
tooltip | The 'Having some trouble?' text that shows before manual capture | Font, text size, text colour, background colour | Only appears for manual capture |
actionbar | The colour for the words 'Auto capture' | Font, text size, text colour, background colour | Only appears in auto capture |
| oval | The colours surrounding the face oval, if a face is seen or not | Colour for face present, or face not present | |
| confirm | The text on the confirmation screen, after a manual capture | Font, text colour, text size | Only appears for manual capture |
| confirmation_background_color | The colour of the confirmation scree, after a manual capture | Background colour | Only appears for manual capture |
Selfie capture - Messages, labels, and other text
Text values in the document capture widget can be changed by including values in a Localizable.strings file in your app. Adding the following key/values will change the following messages.
Due to the implementation of the third party framework that does the capture, you will have to make sure your Localizable.strings file is a proper 'localized' file in Xcode. The name of the file is not enough, it will have to be localised for a language, which will put it inside a directory named 'en.lproj' or something similar.
If your strings file is not properly localised, your settings may be ignored.
An example localizable.strings file that contains some of these keys is available on the greenID Mobile release website.
| Key | Default string | Used by |
|---|---|---|
button_confirm | This is me! | Button text to confirm selfie, after a manual capture |
button_retake | Retake | Button text to re-attempt selfie capture, after a manual capture |
title_review_selfie | Review your Selfie. | Heading on the selfie review screen, after a manual capture. Note that there is not much room to fit more text in this area. Longer sentences will be truncated. |
overlay_please_hold_still | PLEASE HOLD STILL | Dialog text that shows as the image is being captured |
overlay_no_face_found | Please center your\nhead in the oval. | Dialog text that shows if no face is found during auto capture |
tooltip_selfie_manual_capture_heading | Having some trouble? | Text in dialog that shows just before manual capture |
tooltip_selfie_manual_capture | Take your photo using the\ncapture button below. | Text in dialog that shows just before manual capture |
alert_selfie_cancel_message | Are you sure you want to exit? | Cancel dialog text |
alert_selfie_cancel_title | Cancel Capture | Cancel dialog heading |
alert_selfie_positive_button | Yes, I\'m sure | Cancel dialog button text - to cancel |
alert_selfie_negative_button | No, go back | Cancel dialog button text - to continue capture |
overlay_selfie_line1 | Align your head\ninside the oval. | The instruction screen before the selfie capture |
overlay_selfie_line2 | HOLD STEADY WHEN READY | The instruction screen before the selfie capture - second line |
selfie_overlay_gotit_button | Got it! | The button text on the instruction screen before the selfie capture |
selfie_capture_mode | AUTO\nCAPTURE | The text showing that Auto capture is occurring |
label_take_selfie | Take a Selfie. | Text at the bottom of the screen while the selfie capture is being attempted |
Selfie capture reference images
The following images show labels for the keys in the Localizable.strings and Selfie.json files. The Localizable.strings keys are shown in blue, and the Selfie.json keys are shown in yellow.
6. 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