Guide d'intégration iOS

Le SDK de vérification comportementale iOS d'EngageLab est conçu pour les développeurs intégrant des clients natifs iOS. Le SDK ne dépend d'aucune bibliothèque tierce.

Présentation du produit

Prérequis environnementaux

Importation du SDK

1. Si vous ajoutez le SDK manuellement, glissez le fichier GTCaptcha4.framework obtenu lors du téléchargement dans votre projet, en vous assurant que l'option Copy items if needed est cochée.

   Utilisez la méthode Linked Frameworks and Libraries pour importer le framework. Après avoir glissé GTCaptcha4.framework dans le projet, assurez-vous que le fichier .framework est ajouté à PROJECT -> Build Phases -> Linked Frameworks and Libraries.

   

   Le SDK fournit un format XCFramework, situé dans le répertoire SDK -> XCFramework sous les fichiers téléchargés sous le nom GTCaptcha4.xcframework.

2. Pour les Category dans les bibliothèques statiques, ajoutez -ObjC à Other Linker Flags dans Build Settings pour la cible concernée.

   

3. Vous devez également inclure GT4Captcha4.Bundle dans votre projet ; sinon, la vérification ne fonctionnera pas. Glissez le GTCaptcha4.Bundle du répertoire SDK dans votre projet.

   

Lors de la WWDC23, Apple a annoncé de nouvelles politiques de confidentialité pour les applications (y compris les SDK), avec une session dédiée Commencez avec les manifests de confidentialité - WWDC23 - Vidéos - Apple Developer. Le 27 juillet, Apple a publié une mise à jour indiquant qu'à partir de l'automne 2023, si des applications nouvellement téléchargées utilisent des API concernées sans fournir de manifest de confidentialité, vous recevrez une notification par e-mail. À partir du printemps 2024, les manifests de confidentialité deviendront obligatoires. Pour les API concernées et les raisons d'utilisation, consultez : Décrire l'utilisation des API nécessitant une raison | Documentation Apple Developer. Si la raison d'utilisation n'est pas listée, vous pouvez soumettre directement une explication spécifique.

Pour créer un nouveau manifest de confidentialité, consultez Fichiers manifest de confidentialité | Documentation Apple Developer.

Le SDK iOS de vérification comportementale utilise certaines fonctions pour obtenir la capacité disque et des informations de détection d'environnement à des fins de contrôle des risques, impliquant les catégories NSPrivacyAccessedAPICategoryDiskSpace et NSPrivacyAccessedAPICategoryFileTimestamp. Ceci est déclaré ici.

Interface de configuration

Consultez le Processus de structure produit de la vérification comportementale. Vous devez d'abord configurer l'interface côté serveur correspondante sur votre backend et configurer le captchaId et la Key obtenus depuis la console d'administration EngageLab.

Les développeurs intégrant le SDK doivent utiliser les interfaces suivantes fournies par le SDK iOS :

1. Configurer l'initialisation de la vérification à l'aide de l'ID.
2. Démarrer la vérification.
3. Obtenir les paramètres de résultat de la vérification et effectuer une validation secondaire sur les paramètres soumis afin d'éviter toute falsification.
4. Gérer les éventuels problèmes lors de la vérification via les méthodes déléguées d'erreur.

Vous devez implémenter le protocole <GTCaptcha4SessionTaskDelegate> pour gérer les résultats de vérification et les erreurs potentielles.

Consultez les Exemples de code ci-dessous pour le code d'intégration.

Compiler et exécuter votre projet

Compilez votre projet et testez la vérification comportementale.

Exemples de code

Initialisation et appel de la vérification

Importez le fichier d'en-tête de la bibliothèque dynamique de vérification GTCaptcha4.framework dans votre projet.

              
              #import <GTCaptcha4/GTCaptcha4.h>

            

Prenons l'exemple d'une intégration dans un UIButton.

1. Initialisation

   Initialisez une instance du gestionnaire de vérification GTCaptcha4Session. Dans la méthode d'initialisation du UIButton, appelez la méthode d'enregistrement de l'instance GTCaptcha4Session pour obtenir les données d'enregistrement :

   #define captchaID @"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" @interface ViewController () <GTCaptcha4SessionTaskDelegate> @property (strong, nonatomic) IBOutlet UIButton *startBtn; @property (nonatomic, strong) GTCaptcha4Session *captchaSession; @end @implementation ViewController - (GTCaptcha4Session *)captchaSession { if (!_captchaSession) { /// Créer une instance GTCaptcha4SessionConfiguration *config = [GTCaptcha4SessionConfiguration defaultConfiguration]; // config.timeout = 8.0f; /// Définir l'adresse de la page intermédiaire, doit être définie comme dans l'exemple config.resourcePath = @"https://captcha-stat.engagelab.com/www/gt4-index.html"; /// Définir apiServer et staticServer, doivent être définis comme dans l'exemple config.apiServers = @[@"captcha-api.engagelab.com"]; config.staticServers = @[@"captcha-stat.engagelab.com/www/js"]; /// Protocole de requête config.protocol = @"https"; _captchaSession = [GTCaptcha4Session sessionWithCaptchaID:captchaID configuration:config]; _captchaSession.delegate = self; } return _captchaSession; } - (void)viewDidLoad { [super viewDidLoad]; // Pré-initialiser la session de vérification. Si non appelé ici, le chargement paresseux sera utilisé. [self captchaSession]; [self.startBtn addTarget:self action:@selector(start) forControlEvents:UIControlEventTouchUpInside]; }

                 
                 #define captchaID @"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
   
   @interface ViewController () <GTCaptcha4SessionTaskDelegate>
   
   @property (strong, nonatomic) IBOutlet UIButton *startBtn;
   
   @property (nonatomic, strong) GTCaptcha4Session *captchaSession;
   
   @end
   
   @implementation ViewController
   
   - (GTCaptcha4Session *)captchaSession {
       if (!_captchaSession) {
           /// Créer une instance
           GTCaptcha4SessionConfiguration *config = [GTCaptcha4SessionConfiguration defaultConfiguration];
           // config.timeout = 8.0f;
           /// Définir l'adresse de la page intermédiaire, doit être définie comme dans l'exemple
           config.resourcePath = @"https://captcha-stat.engagelab.com/www/gt4-index.html";
           /// Définir apiServer et staticServer, doivent être définis comme dans l'exemple
           config.apiServers = @[@"captcha-api.engagelab.com"];
           config.staticServers = @[@"captcha-stat.engagelab.com/www/js"];
           /// Protocole de requête
           config.protocol = @"https";
           _captchaSession = [GTCaptcha4Session sessionWithCaptchaID:captchaID configuration:config];
   
           _captchaSession.delegate = self;
       }
   
       return _captchaSession;
   }
   
   - (void)viewDidLoad {
       [super viewDidLoad];
   
       // Pré-initialiser la session de vérification. Si non appelé ici, le chargement paresseux sera utilisé.
       [self captchaSession];
   
       [self.startBtn addTarget:self action:@selector(start) forControlEvents:UIControlEventTouchUpInside];
   }
   
               

   Afficher ce bloc de code dans la fenêtre flottante

   Pour d'autres options de configuration, consultez les interfaces ou propriétés définies dans GTCaptcha4SessionConfiguration.

2. Appel de la vérification

   Après l'initialisation, appelez la méthode suivante pour effectuer la vérification :

   - (void)start { [self.captchaSession verify]; }

                 
                 - (void)start {
       [self.captchaSession verify];
   }
   
               

   Afficher ce bloc de code dans la fenêtre flottante

Gestion des résultats de vérification

La vérification n'est complète qu'après validation des résultats. Vous devez gérer les méthodes déléguées suivantes après avoir implémenté le protocole GTCaptcha4SessionTaskDelegate :

              
              - (void)gtCaptchaSession:(GTCaptcha4Session *)captchaSession didReceive:(NSString *)code result:(NSDictionary *)result {
    NSLog(@"result: %@", result);
    // code vaut @"1" si l'utilisateur a réussi la vérification, @"0" si la vérification a échoué
    if ([@"1" isEqualToString:code]) {
        if (result && result.count > 0) {
            // Convertir le dictionnaire au format formulaire pour la soumission (à adapter selon le format de données attendu par l'API)
            __block NSMutableArray<NSString *> *kvPairs = [NSMutableArray array];

            [result enumerateKeysAndObjectsUsingBlock:^(id  _Nonnull key, id  _Nonnull obj, BOOL * _Nonnull stop) {
                if ([key isKindOfClass:[NSString class]] &&
                    [obj isKindOfClass:[NSString class]]) {
                    NSString *kvPair = [NSString stringWithFormat:@"%@=%@", key, obj];
                    [kvPairs addObject:kvPair];
                }
            }];

            NSString *formStr = [kvPairs componentsJoinedByString:@"&"];
            NSData *data = [formStr dataUsingEncoding:NSUTF8StringEncoding];

            // Interface de vérification backend fournie par le service
            NSURL *url = [NSURL URLWithString:@"https://***/validate"];
            NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:url];
            request.HTTPMethod  = @"POST";
            request.HTTPBody    = data;

            // Soumettre au backend pour validation du résultat
            [[[NSURLSession sharedSession] dataTaskWithRequest:request completionHandler:^(NSData * _Nullable data, NSURLResponse * _Nullable response, NSError * _Nullable error) {
                if (!error && data) {
                    // Gérer les résultats de la vérification
                    NSString *msg = [[NSString alloc] initWithData:data encoding:NSUTF8StringEncoding];
                    NSLog(@"result: %@", msg);
                }
                else {
                    NSLog(@"error: %@", error);
                }
            }] resume];
        }
    }
}

            

Gestion des erreurs de vérification

Des erreurs inattendues peuvent survenir lors de la vérification. Vous pouvez les gérer dans la méthode déléguée suivante après avoir implémenté le protocole GTCaptcha4SessionTaskDelegate :

              
              - (void)gtCaptchaSession:(GTCaptcha4Session *)captchaSession didReceiveError:(GTC4Error *)error {
    // Afficher les informations d'erreur et le code d'erreur à l'utilisateur

    // Journaliser les détails de l'erreur
    NSLog(@"error: %@", error.description);
}

            

Il est fortement recommandé d'afficher à l'utilisateur à la fois la raison et le code d'erreur lors de la présentation d'une erreur de vérification, afin de faciliter le diagnostic des problèmes en ligne.

Exemple Swift

Pour un code d'exemple plus détaillé, consultez le Demo officiel fourni. Pour un exemple en Swift, référez-vous au fichier DefaultDemoViewController.swift dans le code source du Demo.