Guía de integración de CAPTCHA para Android
Introducción del producto
| Elemento | Descripción |
|---|---|
| Funciones principales | CAPTCHA de próxima generación que aborda de forma inteligente las pérdidas del negocio y los riesgos de seguridad provocados por ataques automatizados mediante scripts. |
| Política de privacidad del SDK | Política |
| Guía de cumplimiento del SDK | Guía |
| Enlace de descarga del SDK | Descargar |
Requisitos del entorno
| Elemento | Recurso |
|---|---|
| Objetivo de desarrollo | Android 5.0+ (minSdk 21) |
| Entorno de desarrollo | Android Studio 2020.3.1 Arctic Fox+ |
| Herramienta de compilación | Gradle (Android Gradle Plugin 7+) |
| Dependencias del sistema | Ninguna |
Dependencias de terceros del SDK |
Ninguna |
| Incremento del paquete | SDK verificado: 60K |
Integración del SDK
Importación del SDK
Arrastrar el archivo .aar (incluido engagelab_captcha_android_vx.y.z.aar) desde el paquete zip a la carpeta libs del proyecto. Después de arrastrar el archivo .aar a la carpeta libs, asegurarse de que el archivo .aar se haya añadido a la biblioteca. Añadir el siguiente código al archivo build.gradle del proyecto:
repositories {
flatDir {
dirs 'libs'
}
}
Además, añadir manualmente el paquete aar como dependencia (AAR no incluye automáticamente dependencias de terceros, por lo que es necesario añadirlas manualmente):
implementation(name: 'engagelab_captcha_android_vx.y.z', ext: 'aar')
Configuración para proyectos no Kotlin
En la configuración de build.gradle del directorio raíz:
ext.kotlin_version = "1.6.22"
dependencies {
classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version"
}
En la configuración de build.gradle del módulo:
apply plugin: 'kotlin-android'
dependencies {
implementation "org.jetbrains.kotlin:kotlin-stdlib:$kotlin_version"
}
Si existe un conflicto con la versión de
kotlin, excluir la dependencia dekotlin:exclude(group: 'org.jetbrains.kotlin')
Adición de permisos
<!--Required - Default application-->
<uses-permission android:name="android.permission.INTERNET" />
<!--Must be declared for compatibility with API levels below 23 (not included) (i.e., applications running on Android 4.x and 5.x need to declare this) - Default not applied-->
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
Reglas de Proguard
El paquete aar del SDK ya se ha ofuscado. La ofuscación doble puede provocar errores inesperados. De forma predeterminada, el paquete aar incluye la configuración de ofuscación del SDK actual. Tanto las dependencias remotas como las dependencias locales aar garantizan que el SDK no se ofusque de nuevo.
Si es necesario extraer el paquete aar e integrar por separado los archivos jar y de recursos, asegurarse de copiar el contenido del archivo proguard.txt desde el directorio extraído a la configuración de ofuscación de la aplicación para evitar la ofuscación doble del SDK.
Si se utiliza andRes para la ofuscación de recursos, excluir de la ofuscación los recursos incluidos en el SDK para evitar errores causados por recursos ausentes. La configuración de exclusión es la siguiente:
"R.string.gt4_*",
"R.style.gt4_*",
Configuración de la interfaz
Lógica de llamada
- Configurar la inicialización
- Iniciar la verificación
- Obtener el callback de verificación
- Destruir recursos
Para la verificación de comportamiento, consultar el proceso de estructura del producto. Primero se debe configurar la interfaz del lado del servidor correspondiente en el backend y configurar el
captchaIdy elKeyobtenidos en la Consola de gestión de EngageLab.
Inicialización
La información de configuración de inicialización del SDK puede colocarse en el método onCreate u onCreateView para inicializar.
Descripción del método
public static GTCaptcha4Client getClient(Context context);
public GTCaptcha4Client init(String captchaId);
public GTCaptcha4Client init(String captchaId, GTCaptcha4Config config)
Descripción de parámetros
| Parámetro | Tipo | Descripción |
|---|---|---|
context |
Context |
Objeto Context; debe ser una instancia de Activity |
appId |
String |
APP_ID, parámetro obligatorio |
config |
GTCaptcha4Config |
Objeto de configuración, opcional |
El método
init()inicia la precarga. Si la inicialización se realiza en el métodoonCreateuonCreateView, el proceso de verificación se precargará, lo que permite una verificación más rápida. Si se llama ainit()en el momento de la verificación, la velocidad de carga será más lenta que con la precarga. Se recomienda inicializar en el métodoonCreateuonCreateView.
Iniciar verificación
Iniciar el proceso de verificación.
Descripción del método
public void verifyWithCaptcha();
Cancelar verificación
Cancelar el proceso de verificación y cerrar la ventana de verificación.
Descripción del método
public void cancel();
Habilitar/deshabilitar la monitorización de registros
Configurar para habilitar o deshabilitar la monitorización de registros.
Descripción del método
public void setLogEnable(boolean enable);
Obtener el callback de verificación
public GTCaptcha4Client addOnSuccessListener(OnSuccessListener listener);
public GTCaptcha4Client addOnFailureListener(OnFailureListener listener);
public GTCaptcha4Client addOnWebViewShowListener(OnWebViewShowListener listener);
Ejemplo de código
gtCaptcha4Client.addOnSuccessListener(new GTCaptcha4Client.OnSuccessListener() {
@Override
public void onSuccess(boolean status, String response) {
if(status){
// TODO Enable secondary verification
}else {
// TODO User answer verification failed
}
}
}).addOnFailureListener(new GTCaptcha4Client.OnFailureListener() {
@Override
public void onFailure(String error) {
}
}).addOnWebViewShowListener(new GTCaptcha4Client.OnWebViewShowListener() {
@Override
public void onWebViewShow() {
}
})
Destruir recursos
Destruir los recursos en el ciclo de vida onDestroy
public void onDestroy(){
super.onDestroy();
if(gtCaptcha4Client != null){
gtCaptcha4Client.destroy();
}
}
Cambio de orientación de pantalla
@Override
public void onConfigurationChanged(Configuration newConfig) {
super.onConfigurationChanged(newConfig);
if(gtCaptcha4Client != null){
gtCaptcha4Client.configurationChanged(newConfig);
}
}
Ejemplo de código de precarga
@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()
// Set service address
.setResourcePath("https://captcha-stat.engagelab.com/www/gt4-index.html")
.setApiServers(apiServers)
.setStaticServers(staticServers)
.setDebug(true) // TODO Disable in production
.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 Enable secondary verification
}else {
// TODO User answer verification failed
}
}
})
.addOnFailureListener(new GTCaptcha4Client.OnFailureListener {
@Override
public void onFailure(String error) {
}
})
.verifyWithCaptcha();
}
Ejemplo de código de carga normal
private void click(){
String[] apiServers = {"captcha-api.engagelab.com"};
String[] staticServers = {"captcha-stat.engagelab.com/www/js"};
GTCaptcha4Config config = new GTCaptcha4Config.Builder()
// Set service address
.setResourcePath("https://captcha-stat.engagelab.com/www/gt4-index.html")
.setApiServers(apiServers)
.setStaticServers(staticServers)
.setDebug(true) // TODO Disable in production
.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 Enable secondary verification
}else {
// TODO User answer verification failed
}
}
})
.addOnFailureListener(new GTCaptcha4Client.OnFailureListener {
@Override
public void onFailure(String error) {
}
})
.verifyWithCaptcha();
}
Para ejemplos de código más detallados, consultar el Demo oficial
Configuración de parámetros
Configurar parámetros mediante la clase GTCaptcha4Config.Builder
| Definición | Descripción |
|---|---|
setResourcePath |
Debe establecerse en: https://captcha-stat.engagelab.com/www/gt4-index.html |
setApiServers |
Debe establecerse en: captcha-api.engagelab.com |
setStaticServers |
Debe establecerse en: captcha-stat.engagelab.com/www/js |
setParams |
Parámetros adicionales que se pasan al js del frontend para su uso |
setDebug |
Indica si se habilita el modo debug; el valor predeterminado es false; en producción, establecer en false |
setLanguage |
Especificar el idioma; el valor predeterminado es el idioma de la aplicación |
setCanceledOnTouchOutside |
Indica si se cierra al tocar fuera; el valor predeterminado es true |
setTimeOut |
Establecer el tiempo de espera en ms; el valor predeterminado es 10000 |
setBackgroundColor |
Establecer el color de fondo; el valor predeterminado es transparente |
setDialogStyle |
Establecer el estilo de tema del diálogo; el valor predeterminado es gt4_captcha_dialog_style |
setDialogShowListener |
Establecer el callback del listener cuando se muestra la ventana de verificación |
build |
Crear el objeto GTCaptcha4Config |
Los parámetros se pueden configurar mediante la interfaz setParams según la documentación de la API
La interfaz
setParamssolo acepta tipos de datos básicos, cadenas y datos de tipoJSONArray
Gestión de errores
Durante la verificación pueden producirse errores inesperados. Se pueden gestionar mediante la implementación de la interfaz addOnFailureListener y su tratamiento en el siguiente método de callback:
Nota: Los callbacks de error incluyen cancelaciones de verificación iniciadas por el usuario, que pueden filtrarse por separado.
gtCaptcha4Client.addOnFailureListener(new GTCaptcha4Client.OnFailureListener() {
@Override
public void onFailure(String error){
// Example of returned error content
// {"code":"-14460","msg":"Verification session canceled","desc":{"description":"User cancelled 'Captcha'"}}
// You can parse the error as JSON, replace the error description, and retain the error code
Toast.makeText(context, "Verification Error: $error", Toast.LENGTH_SHORT).show()
}
Se recomienda encarecidamente mostrar el código de error junto con el motivo del error al usuario para facilitar la resolución de problemas en línea.
Consultar la siguiente lista para ver posibles códigos de error: Lista de códigos de error
