There are a number of pieces of the UI that can be customised in the SDK. This should be done in conjunction with CSS customisation and iOS customisation. To give the best user experience, you should make your CSS and SDK customisations consistently.

To customise the native Android user interface, simply override the resources provided by the greenidsdk_resources module, in your application's /res/ folder. Your build system will determine which resources are used in your app - resources that get included later in the build process will override earlier values.

We recommend that you make any changes in your own application's /res/ folder, rather than changing the greenidsdk_resources module directly. This makes it easier for you to update to later versions of the Android 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.

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.

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.

Example loading screen

Loading screen - Fonts, colours and loading image

The UI of the loading screens can be changed by putting values into XML files, located in the 'res' folder of your app. Make sure you are changing your own copy of these files. Don't modify the SDK files directly, as that will make future upgrades harder for you.

You can look inside the greenidsdk_resources module to get examples for these files and values.

Adding theses keys to the matching resource files will change the loading screen as follows:

Key	Used by	Resource file	Default value	Notes
gid_loadingBackgroundColor	The loading screen background colour	`/res/values/colors.xml`	#FFFFFF	Should be an html hex code
fullscreen_dialog_background	The SDK startup background colour	`/res/values/colors.xml`	#FFFFFF	Should be an html hex code
gid_loadingSecondaryFontColor	The loading screen secondary font colour	`/res/values/colors.xml`	#AAAAAA	Not used in Android SDK at present, for future compatibility with iOS SDK settings
gid_loadingFontColor	The loading screen font colour	`/res/values/colors.xml`	#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_loadingFontSize	The loading screen font size	`/res/values/dimens.xml`	24dp
gid_loadingFontFamily	The loading screen font family	`/res/values/strings.xml`	helvetica_thin.ttf	Copy the font file into an `assets/fonts` folder to include it in your app
spinner_grey.gif	The loading screen spinner graphic	`/res/drawable/spinner_grey.gif`		Use an animated gif

Loading screen - Text values

To change the text values on the loading screens, add values to a /res/values/strings.xml file in your app.

Key	Used by	Resource file	Default value	Notes
gid_default_dialog_text_loading	Most loading screens	`/res/values/strings.xml`	Loading
gid_dialog_text_uploading_documents	After selfie capture	`/res/values/strings.xml`	We\'re uploading your photos. Please wait.
gid_dialog_text_uploading_document	After additional document capture	`/res/values/strings.xml`	We\'re uploading your photo. Please wait.	Only difference between these two is 'photos' is missing the 's'.

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 why the camera permission is needed.

The wording on this dialog can be altered by adding values into a /res/values/strings.xml file in your app.

There are several different wordings that can be changed, depending on whether the user has denied permission once, or always, and depending on whether the process can continue with or without the camera.

You can look inside the greenidsdk_resources module to see the default values in strings.xml.

Camera permissions messages

Key	Used by	Resource file
When skipping the camera is allowed:
gid_camera_permission_dialog_skip_allowed_title	Title of the dialog box, if skipping the camera is allowed	`/res/values/strings.xml`
gid_camera_permission_dialog_skip_allowed_message	Message, if skipping the camera is allowed	`/res/values/strings.xml`
gid_camera_permission_dialog_skip_allowed_positive_button	Try again button text, if skipping the camera is allowed	`/res/values/strings.xml`
gid_camera_permission_dialog_skip_allowed_negative_button	Continue without the camera button text, if skipping the camera is allowed	`/res/values/strings.xml`
When the user has denied permission, and skipping the camera is allowed:
gid_camera_permission_dialog_skip_allowed_always_deny_title	Title of the dialog box, if user has denied permission always, and skipping the camera is allowed	`/res/values/strings.xml`
gid_camera_permission_dialog_skip_allowed_always_deny_message	Message, if user has denied permission always, and skipping the camera is allowed	`/res/values/strings.xml`
gid_camera_permission_dialog_skip_allowed_always_deny_button	Continue button text, if user has denied permission always, and skipping the camera is allowed	`/res/values/strings.xml`
When skipping the camera is not allowed:
gid_camera_permission_dialog_skip_not_allowed_title	Title of the dialog box, if skipping the camera is not allowed	`/res/values/strings.xml`
gid_camera_permission_dialog_skip_not_allowed_message	Message, if skipping the camera is not allowed	`/res/values/strings.xml`
gid_camera_permission_dialog_skip_not_allowed_positive_button	Try again button text, if skipping the camera is not allowed	`/res/values/strings.xml`
gid_camera_permission_dialog_skip_not_allowed_negative_button	Cancel button text, if skipping the camera is not allowed	`/res/values/strings.xml`
When the user has denied permission, and skipping the camera is not allowed:
gid_camera_permission_dialog_skip_not_allowed_always_deny_title	Title of the dialog box, if user has denied permission always, and skipping the camera is not allowed	`/res/values/strings.xml`
gid_camera_permission_dialog_skip_not_allowed_always_deny_message	Message, if user has denied permission always, and skipping the camera is not allowed	`/res/values/strings.xml`
gid_camera_permission_dialog_skip_not_allowed_always_deny_button	Cancel button text, if user has denied permission always, and skipping the camera is not allowed	`/res/values/strings.xml`

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. Make sure you make changes to your own copy of these files in your app. Don't directly change the files in the greenidsdk_resources module, or inside the catfish .aar files.

You can look inside the greenidsdk_resources module to get examples for these files and values.

Document capture UI

Document capture - colours, fonts, buttons

The colours and fonts of the document capture tool can be modified in a file called /assets/documentConfiguration.json. Note that the assets directory is separate from the usual res directory.

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.

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 sometimes in Alpha-R-G-B 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.

Key	Used by	Options	Notes
icon_help	The image used for the 'help' button	Image, and border appearance
icon_camera	The image used for the manual capture button	Image, and border appearance	Only appears for manual capture
icon_close	The image used to cancel the capture	Image, and border appearance
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
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 /res/values/document_messages.xml file in your app. Note that we use the 'flash enabled capture', so any customisation should be made to the string resources for flash enabled capture. Not all values in this file are used by greenID Mobile SDK - the following list shows values that we use:

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	HOLD STEADY	Dialog box that covers screen when the camera is capturing the licence flash image
second_overlay_licence_text_line2	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	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	HOLD STEADY	Dialog box that covers screen when the camera is capturing the South African Booklet flash image
second_overlay_greenId_text_line2	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 document_messages.xml and documentConfiguration.json files. The document_messages.xml keys are shown in blue, and the documentConfiguration.json keys are shown in yellow.

4. Changing the document review screen UI

The document review screen appears immediately after a document capture. Some of the text on this screen can be customised by making changes in a /res/values/strings.xml file in your app. Parts of the text on this screen are rewritten depending on the document type, and they cannot be customised at this point.

The text strings for this screen can contain basic HTML to make words bolded.

Document review screen UI

Note that the iOS implementation does not allow customising the text on this screen. If you customise your Android app, you will not be able to make your iOS app match on this screen.

Edit your /res/values/strings.xml file to change the following:

Key	Default string	Used by
gid_id_review_screen_confirm_button_text	CONFIRM	The button text to confirm the capture is OK
gid_id_review_screen_confirm_retake_text	RE-TAKE	The button text to attempt another capture
gid_id_review_screen_confirm_text	Please <b>confirm:</b>	First line of text
gid_id_review_screen_document_in_focus_confirm_text	It\'s <b>in focus</b>	Third 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>	Fourth line of text

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. Make sure you make changes to your own copy of these files in your app. Don't directly change the files in the greenidsdk_resources module, or inside the catfish .aar files.

You can look inside the greenidsdk_resources module to get examples for these files and values.

Selfie capture UI

Selfie capture - colours, fonts

The colours and fonts of the document capture tool can be modified in a file called /assets/selfieConfigurations.json. Note that the assets directory is separate from the usual res directory.

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.

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 sometimes in Alpha-R-G-B 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.

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	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	Image, and border appearance
icon_camera	The image used for the manual capture button	Image, and border appearance	Only appears for manual capture
icon_close	The image used to cancel the capture	Image, and border appearance
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 /res/values/selfie_messages.xml file in your app. Not all values in this file are used by greenID Mobile SDK - the following list shows values that we use:

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
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 selfie_messages.xml and selfieConfigurations.json files. The selfie_messages.xml keys are shown in blue, and the selfieConfigurations.json keys are shown in yellow.