本文為您介紹Android客戶端圖形認證的集成方法及接口的功能示例。
接入步驟
下載SDK
登錄號碼認證產品控制臺,在概覽頁面右側API&SDK區域,單擊立即下載,進入API&SDK頁面,根據頁面提示下載并解壓對應SDK。
導入SDK
將SDK包中的.aar文件(包括alicom_captcha_android_vx.y.z_date.aar )拖拽到工程中的libs文件夾下,檢查.aar文件是否被添加到Library ,并在項目的build.gradle下添加如下代碼:
repositories {
flatDir {
dirs 'libs'
}
}
給.aar包添加依賴(AAR默認不傳遞第三方依賴,需要您手動添加):
implementation(name: 'alicom_captcha_android_vx.y.z_date', ext: 'aar')
非Kotlin工程配置
在根目錄build.gradle配置:
ext.kotlin_version = "1.4.10"
dependencies {
classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version"
}
在引入模塊build.gradle配置:
apply plugin: 'kotlin-android'
dependencies {
implementation "org.jetbrains.kotlin:kotlin-stdlib:$kotlin_version"
}
若Kotlin版本存在沖突,剔除Kotlin依賴exclude(group:'org.jetbrains.kotlin')
即可。
添加權限
<!--必選-默認申請-->
<uses-permission android:name="android.permission.INTERNET" />
<!--必選-默認沒有申請-->
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<!--可選-6.0或以上需動態申請(存儲日志方便分析報錯,日志路徑 /sdcard/Android/data/Your
PackageName/files/Alicom/captcha_log.txt)-->
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
混淆規則
驗證SDK已做混淆處理,集成時請帶上混淆規則,勿再次混淆SDK。
-dontwarn com.geetest.gtcaptcha4.alicom.**
-keep class com.geetest.gtcaptcha4.alicom.**{*;}
若使用資源混淆工具,請添加白名單配置:
"R.string.gt4_*",
"R.style.gt4_*",
創建認證方案
您使用SDK時,會用到密鑰參數信息,請先在圖形認證方案管理控制臺,新增圖形認證方案,獲取密鑰參數(包括appId
、appKey
)信息。
配置接口
初始化
SDK初始化配置信息,可放在onCreate
或onCreateView
方法進行初始化。
public static AlicomCaptchaClient getClient(Context context);
public AlicomCaptchaClient init(String captchaId);
public AlicomCaptchaClient init(String captchaId, AlicomCaptchaConfig config)
參數 | 類型 | 說明 |
context | context | 上下文對象,必須為Activity實例。 |
appId | String | 驗證ID,請傳入在控制臺創建認證方案后生成的 |
config | AlicomCaptchaConfig | 參數配置對象,非必填參數。 |
init()
方法啟動預加載,若在onCreate
或onCreateView
方法進行初始化,則會提前加載驗證流程,可更快喚起驗證。若在需要喚起驗證時機再 init() ,則加載速度比預加載慢,建議在onCreate
或onCreateView
方法進行初始化。
啟動驗證
開始驗證流程。
public void verifyWithCaptcha();
取消驗證
取消驗證流程,關閉驗證窗口。
public void cancel();
開啟/關閉日志監控
設置開啟或關閉日志打印監控。
public void setLogEnable(boolean enable);
獲取驗證回調
public AlicomCaptchaClient addOnSuccessListener(OnSuccessListener listener);
public AlicomCaptchaClient addOnFailureListener(OnFailureListener listener);
代碼示例
AlicomCaptchaClient.addOnSuccessListener(new
AlicomCaptchaClient.OnSuccessListener() {
@Override
public void onSuccess(boolean status, String response) {
if(status){
// TODO 開啟二次驗證
}else {
// TODO 用戶答案驗證錯誤
}
}
}).addOnFailureListener(new AlicomCaptchaClient.OnFailureListener() {
@Override
public void onFailure(String error) {
}
})
銷毀資源
在onDestroy
生命周期銷毀資源。
public void onDestroy(){
super.onDestroy();
if(AlicomCaptchaClient != null){
AlicomCaptchaClient.destroy();
}
}
橫豎屏切換
@Override
public void onConfigurationChanged(Configuration newConfig) {
super.onConfigurationChanged(newConfig);
if(AlicomCaptchaClient != null){
AlicomCaptchaClient.configurationChanged(newConfig);
}
}
預加載代碼示例
@Override
public void onViewCreated(View view, Bundle savedInstanceState){
super.onViewCreated(view, savedInstanceState);
AlicomCaptchaConfig config = new AlicomCaptchaConfig.Builder()
.setDebug(true) // TODO 線上務必關閉
.setLanguage("zh")
.setTimeOut(10000)
.setCanceledOnTouchOutside(true)
.build();
AlicomCaptchaClient = AlicomCaptchaClient.getClient(activity)
.init("your captcha_id", config);
}
private void click(){
AlicomCaptchaClient.addOnSuccessListener(new
AlicomCaptchaClient.OnSuccessListener {
@Override
public void onSuccess(boolean status, String response) {
if(status){
// TODO 開啟二次驗證
}else {
// TODO 用戶答案驗證錯誤
}
}
})
.addOnFailureListener(new AlicomCaptchaClient.OnFailureListener {
@Override
public void onFailure(String error) {
}
})
.verifyWithCaptcha();
}
正常加載代碼示例
private void click(){
AlicomCaptchaConfig config = new AlicomCaptchaConfig.Builder()
.setDebug(true) // TODO 線上務必關閉
.setLanguage("zh")
.setTimeOut(10000)
.setCanceledOnTouchOutside(true)
.build();
AlicomCaptchaClient = AlicomCaptchaClient.getClient(activity)
.init("your captcha_id", config)
.addOnSuccessListener(new AlicomCaptchaClient.OnSuccessListener {
@Override
public void onSuccess(boolean status, String response) {
if(status){
// TODO 開啟二次驗證
}else {
// TODO 用戶答案驗證錯誤
}
}
})
.addOnFailureListener(new AlicomCaptchaClient.OnFailureListener {
@Override
public void onFailure(String error) {
}
})
.verifyWithCaptcha();
}
參數配置
通過AlicomCaptchaConfig.Builder
類配置參數。
定義 | 說明 |
setParams | 額外的參數,會被傳遞到前端js中使用 |
setDebug | 是否debug模式,默認false |
setLanguage | 指定語言,默認跟隨應用語言。支持的語言及語言短碼請參見多語言短碼。 |
setCanceledOnTouchOutside | 點擊區域外是否消失,默認true |
setTimeOut | 設置超時,單位:ms ,默認10000ms |
setResourcePath | 設置中間地址,默認加載本地html文件 |
setBackgroundColor | 設置背景顏色,默認透明 |
setDialogStyle | 設置對話框的主題樣式,默認值gt4_captcha_dialog_style |
setDialogShowListener | 設置驗證窗口顯示的監聽回調 |
build | 構建 |
可通過setParams接口配置參數,該接口僅接收基本數據類型、字符串、JSONArray類型的數據。
驗證過程中可能發生一些預料之外的錯誤,您可以實現
addOnFailureListener
后,在下面的回調方法中進行處理,錯誤回調包括用戶主動取消驗證,可單獨過濾掉。建議向用戶展示驗證錯誤原因時,同時展示錯誤碼,方便后續排查線上問題。其他錯誤詳情也可參見錯誤碼。
AlicomCaptchaClient.addOnFailureListener(new AlicomCaptchaClient.OnFailureListener() { @Override public void onFailure(String error){ // 返回error內容示例 // {"code":"-14460","msg":"驗證會話已取消","desc":{"description":"User cancelled 'Captcha'"}} // 可對error做json解析,自行替換錯誤描述,保留錯誤碼 Toast.makeText(context, "驗證錯誤: $error", Toast.LENGTH_SHORT).show() }