Guide d'intégration CAPTCHA Android
Présentation du produit
| Élément | Description |
|---|---|
| Fonctionnalités principales | CAPTCHA de nouvelle génération, répond intelligemment aux pertes commerciales et aux risques de sécurité causés par les attaques automatisées de scripts. |
| Politique de confidentialité du SDK | Politique |
| Guide de conformité du SDK | Guide |
| Lien de téléchargement du SDK | Télécharger |
Prérequis système
| Élément | Ressource |
|---|---|
| Cible de développement | Android 5.0+ (minSdk 21) |
| Environnement de développement | Android Studio 2020.3.1 Arctic Fox+ |
| Outil de build | Gradle (Android Gradle Plugin 7+) |
| Dépendances système | Aucune |
| Dépendances tierces du SDK | Aucune |
| Taille du package | SDK vérifié : 60K |
Intégration du SDK
Importation du SDK
Glissez le fichier .aar (incluant engagelab_captcha_android_vx.y.z.aar) depuis le package zip dans le dossier libs de votre projet. Après avoir déplacé le fichier .aar dans le dossier libs, assurez-vous qu'il est ajouté à la bibliothèque. Ajoutez le code suivant dans le fichier build.gradle du projet :
repositories {
flatDir {
dirs 'libs'
}
}
Ajoutez également manuellement le package aar comme dépendance (aar n'inclut pas automatiquement les dépendances tierces, vous devez donc les ajouter manuellement) :
implementation(name: 'engagelab_captcha_android_vx.y.z', ext: 'aar')
Configuration pour les projets non-Kotlin
Dans la configuration build.gradle du répertoire racine :
ext.kotlin_version = "1.6.22"
dependencies {
classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version"
}
Dans la configuration build.gradle du module :
apply plugin: 'kotlin-android'
dependencies {
implementation "org.jetbrains.kotlin:kotlin-stdlib:$kotlin_version"
}
En cas de conflit avec la version de
kotlin, excluez la dépendancekotlin:exclude(group: 'org.jetbrains.kotlin')
Ajout des permissions
<!-- Obligatoire - Application par défaut -->
<uses-permission android:name="android.permission.INTERNET" />
<!-- Doit être déclaré pour la compatibilité avec les API inférieures à 23 (non incluses) (c'est-à-dire que les applications fonctionnant sur Android 4.x et 5.x doivent le déclarer) - Non appliqué par défaut -->
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
Règles Proguard
Le package aar du SDK a déjà été obfusqué. Une double obfuscation peut entraîner des erreurs inattendues. Par défaut, le package aar inclut la configuration d'obfuscation du SDK actuel. Les dépendances distantes et les dépendances locales aar garantissent que le SDK n'est pas obfusqué à nouveau. Si vous devez extraire le package aar et intégrer séparément les fichiers jar et ressources, assurez-vous de copier le contenu du fichier proguard.txt du répertoire extrait dans la configuration d'obfuscation de votre application pour éviter une double obfuscation du SDK.
Si vous utilisez andRes pour l'obfuscation des ressources, excluez les ressources incluses dans le SDK de l'obfuscation pour éviter les erreurs dues à des ressources manquantes. La configuration d'exclusion est la suivante :
"R.string.gt4_*",
"R.style.gt4_*",
Configuration de l'interface
Logique d'appel
- Configurer l'initialisation
- Démarrer la vérification
- Obtenir le callback de vérification
- Détruire les ressources
Consultez le Processus de structure produit pour la vérification comportementale. Vous devez d'abord configurer l'interface côté serveur correspondante sur votre backend et configurer le
captchaIdet laKeyobtenus depuis la Console d'administration EngageLab.
Initialisation
Les informations de configuration de l'initialisation du SDK peuvent être placées dans la méthode onCreate ou onCreateView pour l'initialisation.
Description des méthodes
public static GTCaptcha4Client getClient(Context context);
public GTCaptcha4Client init(String captchaId);
public GTCaptcha4Client init(String captchaId, GTCaptcha4Config config)
Description des paramètres
| Paramètre | Type | Description |
|---|---|---|
context |
Context |
Objet Context, doit être une instance d'Activity |
appId |
String |
APP_ID, paramètre obligatoire |
config |
GTCaptcha4Config |
Objet de configuration, optionnel |
La méthode
init()lance le préchargement. Si l'initialisation est effectuée dans la méthodeonCreateouonCreateView, le processus de vérification sera préchargé, permettant une vérification plus rapide. Siinit()est appelé au moment de la vérification, la vitesse de chargement sera plus lente que le préchargement. Il est recommandé d'initialiser dans la méthodeonCreateouonCreateView.
Démarrer la vérification
Démarrer le processus de vérification.
Description de la méthode
public void verifyWithCaptcha();
Annuler la vérification
Annuler le processus de vérification et fermer la fenêtre de vérification.
Description de la méthode
public void cancel();
Activer/désactiver la surveillance des logs
Définir l'activation ou la désactivation de la surveillance des logs.
Description de la méthode
public void setLogEnable(boolean enable);
Obtenir le callback de vérification
public GTCaptcha4Client addOnSuccessListener(OnSuccessListener listener);
public GTCaptcha4Client addOnFailureListener(OnFailureListener listener);
public GTCaptcha4Client addOnWebViewShowListener(OnWebViewShowListener listener);
Exemple de code
gtCaptcha4Client.addOnSuccessListener(new GTCaptcha4Client.OnSuccessListener() {
@Override
public void onSuccess(boolean status, String response) {
if(status){
// TODO Activer la vérification secondaire
}else {
// TODO Échec de la vérification de la réponse utilisateur
}
}
}).addOnFailureListener(new GTCaptcha4Client.OnFailureListener() {
@Override
public void onFailure(String error) {
}
}).addOnWebViewShowListener(new GTCaptcha4Client.OnWebViewShowListener() {
@Override
public void onWebViewShow() {
}
})
Détruire les ressources
Détruire les ressources dans le cycle de vie onDestroy
public void onDestroy(){
super.onDestroy();
if(gtCaptcha4Client != null){
gtCaptcha4Client.destroy();
}
}
Changement d'orientation d'écran
@Override
public void onConfigurationChanged(Configuration newConfig) {
super.onConfigurationChanged(newConfig);
if(gtCaptcha4Client != null){
gtCaptcha4Client.configurationChanged(newConfig);
}
}
Exemple de code de préchargement
@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()
// Définir l'adresse du service
.setResourcePath("https://captcha-stat.engagelab.com/www/gt4-index.html")
.setApiServers(apiServers)
.setStaticServers(staticServers)
.setDebug(true) // TODO Désactiver en 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 Activer la vérification secondaire
}else {
// TODO Échec de la vérification de la réponse utilisateur
}
}
})
.addOnFailureListener(new GTCaptcha4Client.OnFailureListener {
@Override
public void onFailure(String error) {
}
})
.verifyWithCaptcha();
}
Exemple de code de chargement normal
private void click(){
String[] apiServers = {"captcha-api.engagelab.com"};
String[] staticServers = {"captcha-stat.engagelab.com/www/js"};
GTCaptcha4Config config = new GTCaptcha4Config.Builder()
// Définir l'adresse du service
.setResourcePath("https://captcha-stat.engagelab.com/www/gt4-index.html")
.setApiServers(apiServers)
.setStaticServers(staticServers)
.setDebug(true) // TODO Désactiver en 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 Activer la vérification secondaire
}else {
// TODO Échec de la vérification de la réponse utilisateur
}
}
})
.addOnFailureListener(new GTCaptcha4Client.OnFailureListener {
@Override
public void onFailure(String error) {
}
})
.verifyWithCaptcha();
}
Pour des exemples de code détaillés, consultez le Demo officiel
Configuration des paramètres
Configurez les paramètres via la classe GTCaptcha4Config.Builder
| Définition | Description |
|---|---|
setResourcePath |
Doit être défini sur : https://captcha-stat.engagelab.com/www/gt4-index.html |
setApiServers |
Doit être défini sur : captcha-api.engagelab.com |
setStaticServers |
Doit être défini sur : captcha-stat.engagelab.com/www/js |
setParams |
Paramètres supplémentaires transmis au frontend js pour utilisation |
setDebug |
Activer ou non le mode debug, par défaut false, à définir sur false en production |
setLanguage |
Spécifier la langue, par défaut la langue de l'application |
setCanceledOnTouchOutside |
Fermer lors d'un clic en dehors, par défaut true |
setTimeOut |
Définir le délai d'expiration en ms, par défaut 10000 |
setBackgroundColor |
Définir la couleur de fond, par défaut transparent |
setDialogStyle |
Définir le style du thème du dialogue, par défaut gt4_captcha_dialog_style |
setDialogShowListener |
Définir le callback lors de l'affichage de la fenêtre de vérification |
build |
Construire l'objet GTCaptcha4Config |
Les paramètres peuvent être configurés via l'interface setParams selon la documentation de l'API.
L'interface
setParamsn'accepte que les types de données de base, les chaînes de caractères et les données de typeJSONArray.
Gestion des erreurs
Des erreurs inattendues peuvent survenir lors de la vérification. Vous pouvez les gérer en implémentant l'interface addOnFailureListener et en les traitant dans la méthode de callback suivante :
Remarque : Les callbacks d'erreur incluent les annulations de vérification initiées par l'utilisateur, qui peuvent être filtrées séparément.
gtCaptcha4Client.addOnFailureListener(new GTCaptcha4Client.OnFailureListener() {
@Override
public void onFailure(String error){
// Exemple de contenu d'erreur retourné
// {"code":"-14460","msg":"Vérification annulée","desc":{"description":"L'utilisateur a annulé 'Captcha'"}}
// Vous pouvez analyser l'erreur en JSON, remplacer la description de l'erreur et conserver le code d'erreur
Toast.makeText(context, "Erreur de vérification : $error", Toast.LENGTH_SHORT).show();
}
});
Il est fortement recommandé d'afficher le code d'erreur ainsi que la raison de l'erreur à l'utilisateur pour faciliter la résolution des problèmes en ligne.
Consultez la liste suivante pour les codes d'erreur possibles : Liste des codes d'erreur
