All Products
Search
Document Center

ID Verification:Custom UI configuration for the iOS SDK

Last Updated:Dec 04, 2025

The ID Verification iOS SDK provides the setCustomUI interface to customize UI colors and icons. You can apply a custom UI by passing a configuration to this interface as a file or in JSON data format. This topic describes the UI customization interface and provides related code examples.

Note

Some custom configurations may require an SDK upgrade. We recommend that you upgrade the SDK to the latest version before you use them. If there is a conflict between the user interface custom settings and the extension parameters of the authentication interface, the user interface custom settings take precedence. This ensures a consistent and intuitive user experience.

Interface description

Interface definition

The iOS SDK provides the setCustomUI interface to customize UI colors and icons. You can call this method and pass the corresponding parameters to customize the UI.

/** 
 * Set custom UI colors and icons
 *
 * Set custom UI
 * @param configuration - Input JSON string
 * @param completeBlock - Callback for the configuration results
*/
- (void)setCustomUI:(nonnull NSString *)configuration
           complete:(void(^_Nullable)(BOOL success, NSError * _Nullable error))completeBlock;

Request parameters

Name

Type

Description

configuration

NSString

The custom UI configuration as a JSON string.

completeBlock

block

The result callback.

  • success = YES: The configuration is successful.

  • success = NO: The configuration has an issue. For more information, see the returned error message.

Sample code

NSString *jsonString = @"{\"faceConfig\":{\"exitIconBase64\":\"data:image/png;base64,iVBORw0..\"}}";
[[AliyunIdentityPlatform sharedInstance] setCustomUI:@"" complete:^(BOOL success, NSError * _Nullable error) {
     	NSLog(@"%@",error.localizedDescription);       
}];

Custom UI configuration content

Full configuration example

{
  "faceConfig": {
    "exitIconBase64": "exit_icon_base64",
    "faceBGColor": "#FFFFFF",
    "faceTitleColor": "#000000",
    "faceTipColor": "#000000",
    "opFailedTitleColor": "#000000",
    "opFailedTipColor": "#000000",
    "opFailedConfirmColor": "#4FA3EC",
    "faceProgressEndColor": "#E3824C",
    "exitAlertTitleColor": "#000000",
    "exitAlertMessageColor": "#000000",
    "exitAlertCancelColor": "#4FA3EC",
    "exitAlertConfirmationColor": "#4FA3EC",
    "timeoutAlertTitleColor": "#000000",
    "timeoutAlertMessageColor": "#000000",
    "timeoutAlertConfirmationColor": "#4FA3EC",
    "tooManyRetriesAlertTitleColor": "#000000",
    "tooManyRetriesAlertMessageColor": "#000000",
    "tooManyRetriesAlertConfirmColor": "#4FA3EC",
    "interruptedAlertTitleColor": "#000000",
    "interruptedAlertMessageColor": "#000000",
    "interruptedAlertConfirmColor": "#4FA3EC",
    "permissionFailedAlertTitleColor": "#000000",
    "permissionFailedAlertMessageColor": "#000000",
    "permissionFailedAlertConfirmColor": "#4FA3EC",
    "verifyNetworkErrorAlertTitleColor": "#000000",
    "verifyNetworkErrorAlertMessageColor": "#000000",
    "verifyNetworkErrorAlertConfirmColor": "#4FA3EC",
    "verifyNetworkErrorAlertCancelColor": "#4FA3EC",
    "verifyLoadingColor": "#585858"
  },
  "ocrConfig": {
    "exitIconBase64": "exit_icon_base64",
    "albumBase64": "album_base64",
    "takePhotoBase64": "take_photo_base64",
    "submitBase64": "submit_base64",
    "ocrResultExitIconBase64": "ocr_result_exit_icon_base64",
    "ocrResultTipIconBase64": "ocr_result_tip_icon_base64",
    "ocrTitleColor": "#FFFFFF",
    "ocrBorderColor": "#E3824C",
    "ocrSubmitTitleColor": "#FFFFFF",
    "ocrLoadingColor": "#FFFFFF",
    "failedAlertTitleColor": "#000000",
    "failedAlertMessageColor": "#000000",
    "failedAlertCancelColor": "#4FA3EC",
    "failedAlertConfirmationColor": "#4FA3EC",
    "timeoutAlertTitleColor": "#000000",
    "timeoutAlertMessageColor": "#000000",
    "timeoutAlertConfirmationColor": "#4FA3EC",
    "exitAlertTitleColor": "#000000",
    "exitAlertCancelColor": "#4FA3EC",
    "exitAlertConfirmationColor": "#4FA3EC",
    "ocrResultTitleColor": "#000000",
    "ocrResultTipBGColor": "#DFDFDF",
    "ocrResultTipColor": "#000000",
    "ocrResultInfoTitleColor": "#000000",
    "ocrResultInfoContentColor": "#F6F6F6",
    "ocrResultInfoBorderColor": "#E3824C",
    "ocrResultTipTitleColor": "#D59F9E",
    "ocrResultErrorTipBGColor": "#F6DAD5",
    "ocrResultConfirmBtnDisabledBGColor": "#DADADA",
    "ocrResultConfirmBtnDisabledTitleColor": "#FFFFFF",
    "ocrResultConfirmBtnEnabledBGColor": "",
    "ocrResultConfirmBtnEnabledTitleColor": "#FFFFFF",
    "ocrResultExitAlertTitleColor": "#000000",
    "ocrResultExitAlertCancelColor": "#000000",
    "ocrResultExitAlertConfirmationColor": "#4FA3EC",
    "restrictionsAlertTitleColor": "#000000",
    "restrictionsAlertMessageColor": "#000000",
    "restrictionsAlertConfirmationColor": "#4FA3EC",
    "permissionFailedAlertTitleColor": "#000000",
    "permissionFailedAlertMessageColor": "#000000",
    "permissionFailedAlertConfirmColor": "#4FA3EC",
    "ocrNetworkErrorAlertTitleColor": "#000000",
    "ocrNetworkErrorAlertMessageColor": "#000000",
    "ocrNetworkErrorAlertCancelColor": "#4FA3EC",
    "ocrNetworkErrorAlertConfirmColor": "#4FA3EC",
    "docErrorAlertTitleColor": "#000000",
    "docErrorAlertMessageColor": "#000000",
    "docErrorAlertCancelColor": "#4FA3EC",
    "docErrorAlertConfirmColor": "#4FA3EC",
    "ocrResultNetworkErrorAlertTitleColor": "#000000",
    "ocrResultNetworkErrorAlertMessageColor": "#000000",
    "ocrResultNetworkErrorAlertConfirmColor": "#4FA3EC",
    "ocrResultInfoErrorAlertMessageColor": "#000000",
    "ocrResultInfoErrorAlertConfirmColor": "#4FA3EC",
    "ocrResultLoadingColor": "#FFFFFF"
  }
}

Field configuration effects

faceModule

faceBGColor

faceBGColor

exitIconBase64

exitIconBase64

faceTitleColor

faceTitleColor

faceTipColor

faceTipColor

interruptedAlertTitleColor

interruptedAlertTitleColor

interruptedAlertMessageColor

interruptedAlertMessageColor

interruptedAlertConfirmColor

interruptedAlertConfirmColor

permissionFailedAlertTitleColor

permissionFailedAlertTitleColor

permissionFailedAlertMessageColor

permissionFailedAlertMessageColor

permissionFailedAlertConfirmColor

permissionFailedAlertConfirmColor

tooManyRetriesAlertTitleColor

tooManyRetriesAlertTitleColor

tooManyRetriesAlertMessageColor

tooManyRetriesAlertMessageColor

tooManyRetriesAlertConfirmColor

tooManyRetriesAlertConfirmColor

faceProgressEndColor

faceProgressEndColor

exitAlertTitleColor

exitAlertTitleColor

exitAlertMessageColor

exitAlertMessageColor

exitAlertCancelColor

exitAlertCancelColor

exitAlertConfirmationColor

exitAlertConfirmationColor

timeoutAlertTitleColor

timeoutAlertTitleColor

timeoutAlertMessageColor

timeoutAlertMessageColor

timeoutAlertConfirmationColor

timeoutAlertConfirmationColor

verifyLoadingColor

verifyLoadingColor

verifyNetworkErrorAlertTitleColor

verifyNetworkErrorAlertTitleColor

verifyNetworkErrorAlertMessageColor

verifyNetworkErrorAlertMessageColor

verifyNetworkErrorAlertCancelColor

verifyNetworkErrorAlertCancelColor

verifyNetworkErrorAlertConfirmColor

verifyNetworkErrorAlertConfirmColor

ocrModule

exitIconBase64
exitIconBase64

ocrTitleColor
ocrTitleColor

ocrBorderColor
ocrBorderColor

albumBase64
albumBase64

takePhotoBase64
takePhotoBase64

submitBase64
submitBase64

ocrSubmitTitleColor
ocrSubmitTitleColor

ocrLoadingColor
ocrLoadingColor

ocrNetworkErrorAlertTitleColor
ocrNetworkErrorAlertTitleColor

ocrNetworkErrorAlertMessageColor
ocrNetworkErrorAlertMessageColor

ocrNetworkErrorAlertCancelColor
ocrNetworkErrorAlertCancelColor

ocrNetworkErrorAlertConfirmColor
ocrNetworkErrorAlertConfirmColor

permissionFailedAlertTitleColor
permissionFailedAlertTitleColor

permissionFailedAlertMessageColor
permissionFailedAlertMessageColor

permissionFailedAlertConfirmColor
permissionFailedAlertConfirmColor

docErrorAlertTitleColor
docErrorAlertTitleColor

docErrorAlertMessageColor
docErrorAlertMessageColor

docErrorAlertCancelColor
docErrorAlertCancelColor

docErrorAlertConfirmColor
docErrorAlertConfirmColor

failedAlertTitleColor
failedAlertTitleColor

failedAlertMessageColor
failedAlertMessageColor

failedAlertConfirmationColor
failedAlertConfirmationColor

failedAlertCancelColor
failedAlertCancelColor

restrictionsAlertTitleColor
restrictionsAlertTitleColor

restrictionsAlertMessageColor
restrictionsAlertMessageColor

restrictionsAlertConfirmationColor
restrictionsAlertConfirmationColor

timeoutAlertTitleColor
timeoutAlertTitleColor

timeoutAlertMessageColor
timeoutAlertMessageColor

timeoutAlertConfirmationColor
timeoutAlertConfirmationColor

exitAlertTitleColor
exitAlertTitleColor

exitAlertCancelColor
exitAlertCancelColor

exitAlertConfirmationColor
exitAlertConfirmationColor

ocrResultExitIconBase64
ocrResultExitIconBase64

ocrResultTitleColor
ocrResultTitleColor

ocrResultTipBGColor
ocrResultTipBGColor

ocrResultTipColor
ocrResultTipColor

ocrResultInfoTitleColor
ocrResultInfoTitleColor

ocrResultInfoContentColor
ocrResultInfoContentColor

ocrResultConfirmBtnEnabledBGColor
ocrResultConfirmBtnEnabledBGColor

ocrResultConfirmBtnEnabledTitleColor
ocrResultConfirmBtnEnabledTitleColor

ocrResultTipTitleColor
ocrResultTipTitleColor

ocrResultTipIconBase64
ocrResultTipIconBase64

ocrResultErrorTipBGColor
ocrResultErrorTipBGColor

ocrResultInfoborderColor
ocrResultInfoborderColor

ocrResultConfirmBtnDisabledBGColor
ocrResultConfirmBtnDisabledBGColor

ocrResultConfirmBtnDisabledTitleColor
ocrResultConfirmBtnDisabledTitleColor

ocrResultExitAlertTitleColor
ocrResultExitAlertTitleColor

ocrResultExitAlertCancelColor
ocrResultExitAlertCancelColor

ocrResultExitAlertConfirmationColor
ocrResultExitAlertConfirmationColor

ocrResultNetworkErrorAlertTitleColor
ocrResultNetworkErrorAlertTitleColor

ocrResultNetworkErrorAlertMessageColor
ocrResultNetworkErrorAlertMessageColor

ocrResultNetworkErrorAlertConfirmColor
ocrResultNetworkErrorAlertConfirmColor

ocrResultInfoErrorAlertMessageColor
ocrResultInfoErrorAlertMessageColor

ocrResultInfoErrorAlertConfirmColor
ocrResultInfoErrorAlertConfirmColor

ocrResultLoadingColor
ocrResultLoadingColor

ocrGuideExitIconBase64
ocrGuideExitIconBase64

ocrGuideTitleColor
ocrGuideTitleColor

ocrGuideContentColor
ocrGuideContentColor

ocrGuideStartBtnTextColor
ocrGuideStartBtnTextColor

ocrGuideStartBtnBGColor
ocrGuideStartBtnBGColor

ocrGuideIndicatorUnSelectedColor
ocrGuideIndicatorUnSelectedColor

ocrGuideIndicatorSelectedColor
ocrGuideIndicatorSelectedColor

nfcTitleColor
nfcTitleColor

nfcContentColor
nfcContentColor

nfcConfirmBtnBGColor
nfcConfirmBtnBGColor

nfcConfirmBtnTextColor
nfcConfirmBtnTextColor

nfcInputCheckAlertMessageColor
nfcInputCheckAlertMessageColor

nfcInputCheckAlertConfirmColor
nfcInputCheckAlertConfirmColor

nfcInputPassportEditHintColor
nfcInputPassportEditHintColor

nfcInputBirthdayEditHintColor
nfcInputBirthdayEditHintColor

nfcInputValidityEditHintColor
nfcInputValidityEditHintColor

nfcInputPassportLabelColor
nfcInputPassportLabelColor

nfcInputBirthdayLabelColor
nfcInputBirthdayLabelColor

nfcInputValidityLabelColor
nfcInputValidityLabelColor

nfcInputBirthdayEditColor
nfcInputBirthdayEditColor

nfcInputValidityEditColor
nfcInputValidityEditColor

nfcInputPassportEditColor
nfcInputPassportEditColor

nfcInputTitleColor
nfcInputTitleColor

nfcInputBackAlertTitleColor
nfcInputBackAlertTitleColor

nfcInputBackAlertCancelColor
nfcInputBackAlertCancelColor

nfcInputBackAlertConfirmColor
nfcInputBackAlertConfirmColor

nfcInputNextBtnTextSelectColor
nfcInputNextBtnTextSelectColor

nfcInputNextBtnBGSelectColor
nfcInputNextBtnBGSelectColor

nfcReadBackAlertTitleColor
nfcReadBackAlertTitleColor

nfcReadBackAlertConfirmColor
nfcReadBackAlertConfirmColor

nfcReadBackAlertCancelColor
nfcReadBackAlertCancelColor

ocrAlbumLabelColor
ocrAlbumLabelColor

ocrTakePhotoLabelColor
ocrTakePhotoLabelColor