ID Verification：Native SDK 自定义UI配置接入（新版）

配置生效规则与建议

• 最低 SDK 版本要求：1.4.0 及以上。

• 默认继承机制：未传递的配置项或其样式属性，系统将自动采用默认值。

• 非法配置项处理：

  • 颜色格式须为 #RRGGBB 或 #AARRGGBB。若传入非法值，系统将自动采用默认值，并返回对应错误提示。

  • Base64 图标须为带合法前缀的 Base64 图片字符串（如 data:image/png;base64,...）。若传入非法值，系统将自动采用默认值，并返回对应错误提示。

• 增量配置建议：建议仅传递需要修改的配置项，其余配置项保持默认值，以降低配置复杂度。

接口说明

    /**
     * 设置自定义UI颜色和icon图标
     *
     * @return 配置文件检测出的异常信息。
     * @description 此接口用于设置自定义UI。
     * @paramType paramType 参数类型{@link IDTFacade} ，可传范围
     * {@link IDTFacade#EXT_PARAMS_CONFIG_JSON} | {@link IDTFacade#EXT_PARAMS_CONFIG_ASSETS_NAME}）。
     *
     * @params {@link String} params 参数值，与paramType相对应的值。
     */
    public String setCustomUIConfig(@IDTFacade int paramType, String param) {
     // ...
    }

// 方式一：传入 assets 文件名
String customUIErrMsg = IdentityPlatform.getInstance()
    .setCustomUIConfig(IDTFacade.EXT_PARAMS_CONFIG_ASSETS_NAME, "DTCustomUIConfig.json");

// 方式二：传入 JSON 字符串
String customUIErrMsg = IdentityPlatform.getInstance()
    .setCustomUIConfig(IDTFacade.EXT_PARAMS_CONFIG_JSON, jsonConfig);

// 建议联调阶段打印返回值
Log.d("CustomUI", "errMsg: " + customUIErrMsg);

    /**
     * 设置自定义UI颜色和icon图标
     *
     * @completeBlock 配置文件检测出的异常信息。
     * @configuration 自定义UI的jsonString。
     */
   - (void)setCustomUI:(nonnull NSString *)configuration
           complete:(void(^_Nullable)(BOOL success, NSError * _Nullable error, NSDictionary *warningDict))completeBlock {
    ......
}

[[AliyunIdentityPlatform sharedInstance] setCustomUI:customUIJSON complete:^(BOOL success, NSError * _Nullable error, NSDictionary *warningDict) {
    if (!success) {
        NSLog(@"自定义 UI 解析失败: %@", error.localizedDescription);
    } else if (warningDict.count > 0) {
        NSLog(@"自定义 UI 告警: %@", warningDict);
    }
}];

配置结构概览

新版配置采用 6 个顶层目录，每个顶层目录下包含对应的详细字段配置：

{
  "commonConfig": { },
  "dialogConfig": { },
  "guideConfig": { },
  "ocrConfig": { },
  "faceConfig": { },
  "nfcConfig": { }
}

全量默认配置

以下 JSON 中所有颜色均取 SDK 默认值，Base64 图标以占位符表示。可直接复制后按需修改：

{
  "commonConfig": {
    "loadingMessageColor": "#000000",
    "btnBGColor": "#FF6A00",
    "btnDisableBGColor": "#D5D5D5",
    "btnMessageColor": "#F9F9FA",
    "btnDisableMessageColor": "#F9F9FA",
    "exitIconBase64": "data:image/png;base64,..."
  },
  "dialogConfig": {
    "titleColor": "#000000",
    "messageColor": "#888888",
    "primaryActionColor": "#FF6A00",
    "secondaryActionColor": "#000000",
    "singleActionColor": "#FF6A00"
  },
  "guideConfig": {
    "titleColor": "#3D3D3D",
    "contentColor": "#333333"
  },
  "ocrConfig": {
    "borderColor": "#ffffff",
    "titleColor": "#ffffff",
    "albumLabelColor": "#ffffff",
    "takePhotoLabelColor": "#ffffff",
    "submitTitleColor": "#ffffff",
    "floodLightBase64": "data:image/png;base64,...",
    "unFloodLightBase64": "data:image/png;base64,...",
    "autoScanBase64": "data:image/png;base64,...",
    "takeShootBase64": "data:image/png;base64,...",
    "albumBase64": "data:image/png;base64,...",
    "takePhotoBase64": "data:image/png;base64,...",
    "submitBase64": "data:image/png;base64,...",
    "resultTitleColor": "#000000",
    "resultTipColor": "#000000",
    "resultTipBgColor": "#EDEDED",
    "resultErrorTipColor": "#C80000",
    "resultErrorTipBgColor": "#FFE0DC",
    "resultErrorTipIconBase64": "data:image/png;base64,...",
    "resultInfoTitleColor": "#333333",
    "resultInfoContentColor": "#999999",
    "resultInfoContentBgColor": "#F7F7F7",
    "resultInfoBorderColor": "#FF6A00"
  },
  "faceConfig": {
    "titleColor": "#000000",
    "tipColor": "#000000",
    "bgColor": "#ffffff",
    "progressStartColor": "#80ffffff",
    "progressEndColor": "#FF6A00"
  },
  "nfcConfig": {
    "titleColor": "#3D3D3D",
    "contentColor": "#3D3D3D",
    "readStatusTextColor": "#3D3D3D",
    "readStatusExitBase64": "data:image/png;base64,...",
    "inputTitleColor": "#262626",
    "inputLabelColor": "#333333",
    "inputEditColor": "#333333",
    "inputEditHintColor": "#999999"
  }
}

最小配置示例

仅修改最常用的主按钮和主标题颜色，其余配置项均使用 SDK 默认值：

{
  "commonConfig": {
    "btnBGColor": "#FF6A00",
    "btnMessageColor": "#FFFFFF"
  },
  "ocrConfig": {
    "titleColor": "#FFFFFF"
  },
  "faceConfig": {
    "titleColor": "#000000"
  }
}

详细字段说明与默认值

commonConfig

dialogConfig

guideConfig

ocrConfig

faceConfig

nfcConfig