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