Android CAPTCHA 功能集成指引

產品簡介

項目	說明
主要功能	新一代驗證碼，更智能地解決機器腳本程序自動化攻擊帶來的業務損失與安全隱患
SDK 隱私政策	政策
SDK 合規指引	指引
SDK 下載鏈接	下載

環境需求

項目	資源
開發目標	`Android 5.0+`（minSdk 21）
開發環境	`Android Studio 2020.3.1 Arctic Fox+`
編譯工具	`Gradle` （Android Gradle Plugin 7+）
系統依賴	無
`SDK` 三方依賴	無
包增量	驗證 `SDK`: `60K`

集成 SDK

導入 SDK

將 zip 包中的 .aar 文件（包括 engagelab_captcha_android_vx.y.z.aar ）拖拽到工程中的 libs 文件夾下，在拖入 .aar 到 libs 文件夾後，還要檢查 .aar 是否被添加到 Library，要在項目的 build.gradle 下添加如下代碼：

repositories { flatDir { dirs 'libs' } }

              
              repositories {
    flatDir {
        dirs 'libs'
    }
}

此代碼塊在浮窗中顯示

並且要手動將 aar 包添加依賴 (AAR 默認不傳遞第三方依賴，需要您手動添加)：

implementation(name: 'engagelab_captcha_android_vx.y.z', ext: 'aar')

              
              implementation(name: 'engagelab_captcha_android_vx.y.z', ext: 'aar')

此代碼塊在浮窗中顯示

非 Kotlin 工程配置

在根目錄 build.gradle 配置

ext.kotlin_version = "1.6.22" dependencies { classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version" }

              
              ext.kotlin_version = "1.6.22"

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" }

              
              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" />

              
              <!--必選-默認申請-->
<uses-permission android:name="android.permission.INTERNET" />
<!--兼容到api 23（不含）以下必須聲明（即需要運行在4.x和5.x的應用需要聲明）-默認沒有申請-->
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

此代碼塊在浮窗中顯示

混淆規則

SDK 的 aar 包已做混淆處理，兩次混淆會導致不可預期的錯誤，默認情況下 aar 包內包含當前 SDK 的混淆配置，遠端依賴或者本地 aar 依賴都能確保 SDK 不被二次混淆。如有解壓 aar 包單獨集成 jar 與資源文件的需求，請務必將解壓目錄中的 proguard.txt 文件內容拷貝到應用的混淆配置中，跳過對 SDK 的二次混淆操作。

如果使用了 andRes 進行資源混淆，請將 SDK 內部包含資源排除混淆，避免因找不到資源而報錯。排除配置如下：

"R.string.gt4_*", "R.style.gt4_*",

              
              "R.string.gt4_*",
"R.style.gt4_*",

此代碼塊在浮窗中顯示

配置接口

調用邏輯

配置初始化
啟動驗證
獲取驗證回調
銷毀資源

參考行為驗證的產品結構流程, 必須要先在您的後端搭建相應的服務端接口，並配置從EngageLab管理後台獲取的 captchaId 和 Key

初始化

SDK 初始化配置信息，可放在 onCreate 或者 onCreateView 方法進行初始化

方法描述

public static GTCaptcha4Client getClient(Context context); public GTCaptcha4Client init(String captchaId); public GTCaptcha4Client init(String captchaId, GTCaptcha4Config config)

              
              public static GTCaptcha4Client getClient(Context context);
public GTCaptcha4Client init(String captchaId);
public GTCaptcha4Client init(String captchaId, GTCaptcha4Config config)

此代碼塊在浮窗中顯示

參數說明

參數	類型	說明
`context`	`Context`	上下文對象，必須為 `Activity` 實例
`appId`	`String`	`APP_ID`，必須參數
`config`	`GTCaptcha4Config`	參數配置對象，非必須

init() 方法啟動預加載，若在 onCreate 或者 onCreateView 方法進行初始化，則會提前加載驗證流程，可更快喚起驗證。若在需要喚起驗證時機再 init()，則加載速度比預加載慢，建議在 onCreate 或者 onCreateView 方法進行初始化。

啟動驗證

開始驗證流程

方法描述

public void verifyWithCaptcha();

              
              public void verifyWithCaptcha();

此代碼塊在浮窗中顯示

取消驗證

取消驗證流程，關閉驗證窗口

方法描述

public void cancel();

              
              public void cancel();

此代碼塊在浮窗中顯示

開啟/關閉日誌監控

設置開啟或關閉日誌打印監控

方法描述

public void setLogEnable(boolean enable);

              
              public void setLogEnable(boolean enable);

此代碼塊在浮窗中顯示

獲取驗證回調

public GTCaptcha4Client addOnSuccessListener(OnSuccessListener listener); public GTCaptcha4Client addOnFailureListener(OnFailureListener listener); public GTCaptcha4Client addOnWebViewShowListener(OnWebViewShowListener listener);

              
              public GTCaptcha4Client addOnSuccessListener(OnSuccessListener listener);
public GTCaptcha4Client addOnFailureListener(OnFailureListener listener);
public GTCaptcha4Client addOnWebViewShowListener(OnWebViewShowListener listener);

此代碼塊在浮窗中顯示

代碼示例

gtCaptcha4Client.addOnSuccessListener(new GTCaptcha4Client.OnSuccessListener() { @Override public void onSuccess(boolean status, String response) { if(status){ // TODO 開啟二次驗證 }else { // TODO 用戶答案驗證錯誤 } } }).addOnFailureListener(new GTCaptcha4Client.OnFailureListener() { @Override public void onFailure(String error) { } }).addOnWebViewShowListener(new GTCaptcha4Client.OnWebViewShowListener() { @Override public void onWebViewShow() { } })

              
              gtCaptcha4Client.addOnSuccessListener(new GTCaptcha4Client.OnSuccessListener() {
    @Override
    public void onSuccess(boolean status, String response) {
        if(status){
            // TODO 開啟二次驗證
        }else {
            // TODO 用戶答案驗證錯誤
        }
    }
}).addOnFailureListener(new GTCaptcha4Client.OnFailureListener() {
    @Override
    public void onFailure(String error) {
    }
}).addOnWebViewShowListener(new GTCaptcha4Client.OnWebViewShowListener() {
      @Override
      public void onWebViewShow() {
      }
  })

此代碼塊在浮窗中顯示

銷毀資源

在 onDestroy 生命週期銷毀資源

public void onDestroy(){ super.onDestroy(); if(gtCaptcha4Client != null){ gtCaptcha4Client.destroy(); } }

              
              public void onDestroy(){
    super.onDestroy();
    if(gtCaptcha4Client != null){
        gtCaptcha4Client.destroy();
    }
}

此代碼塊在浮窗中顯示

橫豎屏切換

@Override public void onConfigurationChanged(Configuration newConfig) { super.onConfigurationChanged(newConfig); if(gtCaptcha4Client != null){ gtCaptcha4Client.configurationChanged(newConfig); } }

              
              @Override
public void onConfigurationChanged(Configuration newConfig) {
    super.onConfigurationChanged(newConfig);
    if(gtCaptcha4Client != null){
        gtCaptcha4Client.configurationChanged(newConfig);
    }
}

此代碼塊在浮窗中顯示

預加載代碼示例

@Override public void onViewCreated(View view, Bundle savedInstanceState){ super.onViewCreated(view, savedInstanceState); String[] apiServers = {"captcha-api.engagelab.com"}; String[] staticServers = {"captcha-stat.engagelab.com/www/js"}; GTCaptcha4Config config = new GTCaptcha4Config.Builder() // 設置服務地址 .setResourcePath("https://captcha-stat.engagelab.com/www/gt4-index.html") .setApiServers(apiServers) .setStaticServers(staticServers) .setDebug(true) // TODO 線上務必關閉 .setLanguage("zh") .setTimeOut(10000) .setCanceledOnTouchOutside(true) .build(); gtCaptcha4Client = GTCaptcha4Client.getClient(activity) .init("your captcha_id", config); } private void click(){ gtCaptcha4Client.addOnSuccessListener(new GTCaptcha4Client.OnSuccessListener { @Override public void onSuccess(boolean status, String response) { if(status){ // TODO 開啟二次驗證 }else { // TODO 用戶答案驗證錯誤 } } }) .addOnFailureListener(new GTCaptcha4Client.OnFailureListener { @Override public void onFailure(String error) { } }) .verifyWithCaptcha(); }

              
              @Override
public void onViewCreated(View view, Bundle savedInstanceState){
    super.onViewCreated(view, savedInstanceState);
    String[] apiServers = {"captcha-api.engagelab.com"};
    String[] staticServers = {"captcha-stat.engagelab.com/www/js"};
    GTCaptcha4Config config = new GTCaptcha4Config.Builder()
            // 設置服務地址
            .setResourcePath("https://captcha-stat.engagelab.com/www/gt4-index.html")
            .setApiServers(apiServers)
            .setStaticServers(staticServers)
            .setDebug(true) // TODO 線上務必關閉
            .setLanguage("zh")
            .setTimeOut(10000)
            .setCanceledOnTouchOutside(true)
            .build();
    gtCaptcha4Client = GTCaptcha4Client.getClient(activity)
            .init("your captcha_id", config);
}

private void click(){
    gtCaptcha4Client.addOnSuccessListener(new GTCaptcha4Client.OnSuccessListener {
                @Override
                public void onSuccess(boolean status, String response) {
                    if(status){
                        // TODO 開啟二次驗證
                    }else {
                        // TODO 用戶答案驗證錯誤
                    }
                }
            })
            .addOnFailureListener(new GTCaptcha4Client.OnFailureListener {
                @Override
                public void onFailure(String error) {
                }
            })
            .verifyWithCaptcha();
}

此代碼塊在浮窗中顯示

正常加載代碼示例

private void click(){ String[] apiServers = {"captcha-api.engagelab.com"}; String[] staticServers = {"captcha-stat.engagelab.com/www/js"}; GTCaptcha4Config config = new GTCaptcha4Config.Builder() // 設置服務地址 .setResourcePath("https://captcha-stat.engagelab.com/www/gt4-index.html") .setApiServers(apiServers) .setStaticServers(staticServers) .setDebug(true) // TODO 線上務必關閉 .setLanguage("zh") .setTimeOut(10000) .setCanceledOnTouchOutside(true) .build(); gtCaptcha4Client = GTCaptcha4Client.getClient(activity) .init("your captcha_id", config) .addOnSuccessListener(new GTCaptcha4Client.OnSuccessListener { @Override public void onSuccess(boolean status, String response) { if(status){ // TODO 開啟二次驗證 }else { // TODO 用戶答案驗證錯誤 } } }) .addOnFailureListener(new GTCaptcha4Client.OnFailureListener { @Override public void onFailure(String error) { } }) .verifyWithCaptcha(); }

              
              private void click(){
    String[] apiServers = {"captcha-api.engagelab.com"};
    String[] staticServers = {"captcha-stat.engagelab.com/www/js"};
    GTCaptcha4Config config = new GTCaptcha4Config.Builder()
            // 設置服務地址
            .setResourcePath("https://captcha-stat.engagelab.com/www/gt4-index.html")
            .setApiServers(apiServers)
            .setStaticServers(staticServers)
            .setDebug(true) // TODO 線上務必關閉
            .setLanguage("zh")
            .setTimeOut(10000)
            .setCanceledOnTouchOutside(true)
            .build();
    gtCaptcha4Client = GTCaptcha4Client.getClient(activity)
            .init("your captcha_id", config)
            .addOnSuccessListener(new GTCaptcha4Client.OnSuccessListener {
                @Override
                public void onSuccess(boolean status, String response) {
                    if(status){
                        // TODO 開啟二次驗證
                    }else {
                        // TODO 用戶答案驗證錯誤
                    }
                }
            })
            .addOnFailureListener(new GTCaptcha4Client.OnFailureListener {
                @Override
                public void onFailure(String error) {
                }
            })
            .verifyWithCaptcha();
}

此代碼塊在浮窗中顯示

示例代碼細節參考官方提供的 Demo

參數配置

通過 GTCaptcha4Config.Builder 類配置參數

定義	說明
`setResourcePath`	必須設置為：https://captcha-stat.engagelab.com/www/gt4-index.html
`setApiServers`	必須設置為：captcha-api.engagelab.com
`setStaticServers`	必須設置為：captcha-stat.engagelab.com/www/js
`setParams`	額外的參數，會被會傳遞到前端 `js` 中使用
`setDebug`	是否 `debug` 模式，默認 `false`，線上請置為 `false`
`setLanguage`	指定語言，默認跟隨應用語言
`setCanceledOnTouchOutside`	點擊區域外是否消失，默認 `true`
`setTimeOut`	設置超時，單位 `ms`，默認 10000
`setBackgroundColor`	設置背景顏色，默認透明
`setDialogStyle`	設置對話框的主題樣式，默認值`gt4_captcha_dialog_style`
`setDialogShowListener`	設置驗證窗口顯示的監聽回調
`build`	構建 `GTCaptcha4Config` 對象

可通過 setParams 接口配置參數見接口文檔

setParams 接口只能接收基本數據類型、字符串、JSONArray 類型的數據

處理錯誤

驗證過程中可能發生一些預料之外的錯誤, 您可以通過實現 addOnFailureListener接口後, 在下面的回調方法中進行處理:

注意：錯誤回調包括用戶主動取消驗證，可單獨過濾掉

gtCaptcha4Client.addOnFailureListener(new GTCaptcha4Client.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() }

              
              gtCaptcha4Client.addOnFailureListener(new GTCaptcha4Client.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()
    }

此代碼塊在浮窗中顯示

強烈建議在向用戶展示驗證錯誤原因時，同時展示錯誤碼，方便後續排查線上問題。

可能遇到的錯誤碼請參考後面的列表: Error Code 列表