Intégrer reCAPTCHA Enterprise aux applications iOS

Cette page explique comment intégrer reCAPTCHA Enterprise à votre application iOS.

En raison des différences de taille d'écran, de performances et d'UI des applications sur les appareils mobiles, la case à cocher visuelle reCAPTCHA (Je ne suis pas un robot) n'est pas disponible pour les applications mobiles iOS. À la place, vous pouvez mettre en œuvre votre propre stratégie d'application à plusieurs niveaux, telle qu'un flux MFA pour fournir une autre méthode de remboursement en cas de trafic suspect.

Remarque :Le SDK utilise la réflexion et le code dynamique pour permettre la mise à jour et l'amélioration du système de détection dans les applications ou les SDK déjà déployés. Pour éviter toute interférence avec l'application, l'ensemble des classes disponibles dans le système est limité à une liste soigneusement contrôlée.

Avant de commencer

1. Définissez le SDK minimal de votre application sur iOS 11 ou créez une application mobile.

2. Préparez votre environnement pour reCAPTCHA Enterprise.

3. Créez une clé reCAPTCHA pour la plate-forme d'applications iOS.

   Vous pouvez également copier l'ID d'une clé reCAPTCHA existante pour iOS en effectuant l'une des opérations suivantes:

   • Pour copier l'ID d'une clé existante à partir de la console Google Cloud, procédez comme suit:

     1. Accédez à la page reCAPTCHA Enterprise.

        Accéder à la page reCAPTCHA Enterprise

     2. Dans la liste des clés reCAPTCHA, pointez sur la clé que vous souhaitez copier, puis cliquez sur .
   • Pour copier l'ID d'une clé existante à l'aide de l'API REST, utilisez la méthode projects.keys.list.
   • Pour copier l'ID d'une clé existante à l'aide de la gcloud CLI, exécutez la commande gcloud recaptcha keys list.

4. posséder un compte GitHub ;

5. Lisez les informations sur la confidentialité d'Apple.

Préparer votre environnement iOS

Pour préparer votre environnement de développement, procédez comme suit :

1. Téléchargez et installez la dernière version de Xcode, puis créez une application iOS Single View vide.

2. Téléchargez le SDK en utilisant l'une des méthodes suivantes:

   CocoaPods

   1. Téléchargez et installez CocoaPods.

   2. Créez un fichier Podfile et ajoutez les lignes suivantes à votre Podfile :

      source "https://github.com/CocoaPods/Specs.git"
      
      target 'AppTarget' do
      
        # Podfiles must include use_frameworks! or
        # use_frameworks! :linkage => :static
        use_frameworks!
      
        pod "RecaptchaEnterprise", "18.5.0-beta02"
        ...
      
      end
      

   3. Installez les dépendances requises en exécutant la commande pod update.

      Remarque : L'exécution de pod clone n'installe pas les dépendances requises.

   Gestionnaire de paquets Swift

   1. Dans XCode, sélectionnez File > Add Packages (Fichier > Ajouter des packages), puis saisissez l'URL suivante dans le champ Search (Rechercher) ou Enter Package URL (Saisir l'URL du package) : https://github.com/GoogleCloudPlatform/recaptcha-enterprise-mobile-sdk

   2. Dans la boîte de dialogue XCode, saisissez les informations suivantes:

      • Nom d'utilisateur GitHub.
      • Un jeton d'accès personnel que vous avez créé en suivant les instructions de GitHub. Le Personal Access Token doit être associé aux champs d'application indiqués dans la boîte de dialogue XCode Sign In (Connexion XCode).

      Xcode installe le SDK et ses dépendances requises.

   Flutter

   Pour obtenir des instructions détaillées sur l'utilisation de reCAPTCHA Enterprise via Flutter, consultez la documentation Flutter.

   ReactNative

   Pour obtenir des instructions détaillées sur l'utilisation de reCAPTCHA Enterprise via React Native, consultez la documentation sur React Native.

   Téléchargement direct

   1. Si vous souhaitez télécharger le SDK et ses dépendances en tant que xcframeworks, téléchargez le client.

      Remarque :Ajoutez tous les binaires en tant que xcframeworks statiques.

Configurer l'application

Vous pouvez écrire vos applications en Swift ou en Objective-C.

Pour configurer votre application, ajoutez-y les fichiers suivants:

Swift

1. Si votre application est écrite en Swift, créez un en-tête de pontage Objective-C et incluez l'importation suivante :

   #import <RecaptchaEnterprise/RecaptchaEnterprise.h>
   

Objective-C

1. Si votre application est écrite en Objective-C, créez un fichier Swift factice et incluez l'importation suivante pour vous assurer que Xcode peut trouver et associer les bibliothèques Swift.

   import Foundation
   

2. Pour vous assurer que le code Swift est correctement associé, accédez à Target> Build Settings > Always Embed Swift Standard libraries (Cible > Paramètres de compilation > Toujours intégrer les bibliothèques standards Swift), puis vérifiez que l'option est définie sur Yes.

Intégrer reCAPTCHA Enterprise à votre application iOS

Pour intégrer reCAPTCHA Enterprise à votre application iOS, procédez comme suit dans Xcode :

Remarque :La latence du SDK reCAPTCHA peut être élevée. Il est donc recommandé d'appeler Recaptcha.getClient(siteKey:) et execute() le plus tôt possible, par exemple lors du chargement de l'application. Vous ne devez pas faire en sorte que les éléments d'interface utilisateur bloquent le SDK reCAPTCHA.

1. Pour instancier le SDK avec la clé reCAPTCHA (KEY_ID) que vous avez créée, mettez à jour l'application avec le code suivant:

   Swift avec storyboard

   1. Mettez à jour ViewController.swift.

      Si vous utilisez CocoaPods, ignorez la ligne import RecaptchaEnterprise, car l'instruction d'importation #import <RecaptchaEnterprise/RecaptchaEnterprise.h> du fichier *-Bridging-Header.h est suffisante.

      import RecaptchaEnterprise
      
      class ViewController: UIViewController {
        var recaptchaClient: RecaptchaClient?
      
        override func viewDidLoad() {
          super.viewDidLoad()
          Task {
            do {
              let client = try await Recaptcha.getClient(withSiteKey: "KEY_ID")
              self.recaptchaClient = client
            } catch let error as RecaptchaError {
               print("RecaptchaClient creation error: \(String(describing: error.errorMessage)).")
            }
          }
        }
      }
      

      Si la version minimale de l'OS de votre application est antérieure à la version 13, utilisez plutôt une fermeture finale:

      import RecaptchaEnterprise
      
      class ViewController: UIViewController {
        var recaptchaClient: RecaptchaClient?
      
        override func viewDidLoad() {
          super.viewDidLoad()
          Recaptcha.getClient(withSiteKey: "KEY_ID") { client, error in
            guard let client = client else {
                print("RecaptchaClient creation error: \(error).")
              return
            }
            self.recaptchaClient = client
          }
        }
      }
      

   Swift avec SwiftUI

   1. Créez une classe ViewModel.

      Si vous utilisez CocoaPods, ignorez la ligne import RecaptchaEnterprise, car l'instruction d'importation #import <RecaptchaEnterprise/RecaptchaEnterprise.h> du fichier *-Bridging-Header.h est suffisante.

      import RecaptchaEnterprise
      
      @MainActor class ViewModel: ObservableObject {
        private var recaptchaClient: RecaptchaClient?
      
        init() {
           Task {
            do {
              let client = try await Recaptcha.getClient(withSiteKey: "KEY_ID")
              self.recaptchaClient = client
            } catch let error as RecaptchaError {
               print("RecaptchaClient creation error: \(String(describing: error.errorMessage)).")
            }
          }
        }
      }
      

      Si la version minimale de l'OS de votre application est antérieure à la version 13, utilisez plutôt une fermeture finale:

      import RecaptchaEnterprise
      
      class ViewController: UIViewController {
        var recaptchaClient: RecaptchaClient?
      
        override func viewDidLoad() {
          super.viewDidLoad()
          Recaptcha.getClient(withSiteKey: "KEY_ID") { client, error in
            guard let client = client else {
                print("RecaptchaClient creation error: \(error).")
              return
            }
            self.recaptchaClient = client
          }
        }
      }
      

   2. Instanciez ViewModel dans ContentView.swift.

      import SwiftUI
      import RecaptchaEnterprise
      
      struct ContentView: View {
        @StateObject private var viewModel = ViewModel()
      
        var body: some View {
        }
      }
      
      struct ContentView_Previews: PreviewProvider {
        static var previews: some View {
          ContentView()
        }
      }
      

   Objective-C

   1. Mettez à jour ViewController.h.

      #import <RecaptchaEnterprise/RecaptchaEnterprise.h>
      
      @interface ViewController : UIViewController
      @property (strong, atomic) RecaptchaClient *recaptchaClient;
      @end
      

   2. Mettez à jour ViewController.m.

      @implementation ViewController
      [Recaptcha getClientWithSiteKey:@"KEY_ID"
            completion:^void(RecaptchaClient* recaptchaClient, NSError* error) {
              if (!recaptchaClient) {
                NSLog(@"%@", (RecaptchaError *)error.errorMessage);
                return;
              }
              self->_recaptchaClient = recaptchaClient;
            }
      ];
      @end
      

2. Créez un bouton pour appeler reCAPTCHA Enterprise et déclencher execute().

   Swift avec storyboard

   1. Créez un bouton dans le storyboard.
   2. Créez une action dans ViewController associée au bouton que vous avez créé.

   3. Appelez la méthode execute() en transmettant une action Login pour renvoyer un jeton reCAPTCHA à l'aide de l'extrait de code suivant:

      guard let recaptchaClient = recaptchaClient else {
        print("RecaptchaClient creation failed.")
        return
      }
      Task {
        do {
          let token = try await recaptchaClient.execute(withAction: RecaptchaAction.login)
          print(token)
        } catch let error as RecaptchaError {
          print(error.errorMessage)
        }
      }
      

      Si la version minimale de l'OS de votre application est antérieure à la version 13, utilisez plutôt une fermeture finale:

      guard let recaptchaClient = recaptchaClient else {
        print("RecaptchaClient creation failed.")
        return
      }
      recaptchaClient.execute(withAction: RecaptchaAction.login) { token, error in
        if let token = token {
          print(token)
        } else {
          print(error)
        }
      }
      

   Swift avec SwiftUI

   1. Mettez à jour ViewModel.swift avec le code d'exécution:

      import RecaptchaEnterprise
      
      @MainActor class ViewModel: ObservableObject {
      
        func execute() {
          guard let recaptchaClient = self.recaptchaClient else {
            print("Client not initialized correctly.")
            return
          }
      
          Task {
            do {
              let token = try await recaptchaClient.execute(withAction: RecaptchaAction.login)
              print(token)
            } catch let error as RecaptchaError {
              print(error.errorMessage)
            }
          }
        }
      }
      

      Si la version minimale de l'OS de votre application est antérieure à la version 13, utilisez plutôt une fermeture finale:

      guard let recaptchaClient = recaptchaClient else {
        print("RecaptchaClient creation failed.")
        return
      }
      recaptchaClient.execute(withAction: RecaptchaAction.login) { token, error in
        if let token = token {
          print(token)
        } else {
          print(error)
        }
      }
      

   2. Mettez à jour ContentView.swift.

      import SwiftUI
      import RecaptchaEnterprise
      
      struct ContentView: View {
        @StateObject private var viewModel = ViewModel()
      
        var body: some View {
      
          Button {
            viewModel.execute()
          } label: {
            Text("Execute")
          }.padding()
      
          Spacer()
        }
      }
      
      struct ContentView_Previews: PreviewProvider {
        static var previews: some View {
          ContentView()
        }
      }
      

   Objective-C

   1. Dans le storyboard, créez un bouton.
   2. Créez une action dans ViewController associée au bouton que vous avez créé.

   3. Appelez la méthode execute() en transmettant une action Login pour renvoyer un jeton reCAPTCHA à l'aide de l'extrait de code suivant:

      if (!self->_recaptchaClient) {
        return;
      }
      
      [recaptchaClient execute:RecaptchaAction.login
          completion:^void(NSString* _Nullable  token, NSError* _Nullable error) {
        if (!token) {
          NSLog (@"%@", (RecaptchaError *)error.errorMessage);
          return;
        }
        NSLog (@"%@", token);
      }];
      

3. Testez votre application :

   1. reCAPTCHA Enterprise utilise AppAttest d'Apple dans son moteur de détection. Si vous ne prévoyez pas d'utiliser une clé de test avec un score fixe pour le développement local, procédez comme suit:

      1. Dans Xcode, ajoutez la fonctionnalité App Attest à votre application.

      2. Dans le fichier .entitlements de votre projet, définissez l'environnement App Attest sur production.

   2. Pour nettoyer votre environnement de compilation Xcode, dans le menu Product (Produit), cliquez sur Clean Build Folder (Nettoyer le dossier de compilation).

   3. Pour exécuter l'application, dans le menu Product (Produit), cliquez sur Run (Exécuter).

   4. Dans l'application chargée, cliquez sur le bouton que vous avez créé précédemment.

   5. Observez votre fenêtre de sortie de débogage pour obtenir un jeton reCAPTCHA (chaîne alphanumérique), qui est renvoyé si l'intégration réussit.

Définir un délai avant expiration pour les appels d'API

Vous pouvez spécifier une valeur de délai avant expiration pour les API getClient et execute à l'aide de la propriété withTimeout de chaque API.

Remarque :Un délai avant expiration par défaut de 10 secondes est utilisé pour les API getClient et execute par souci de cohérence.

Swift

1. Définissez un délai d'inactivité lors de l'appel de getClient.

       Task {
         do {
           self.recaptchaClient = try await Recaptcha.getClient(
             withSiteKey: "KEY_ID",
             withTimeout: 15000
           )
         } catch let error as RecaptchaError {
             print("RecaptchaClient creation error: \(String(describing: error.errorMessage)).")
         }
       }
   

   Si la version minimale de l'OS de votre application est antérieure à la version 13, utilisez plutôt une fermeture finale:

     Recaptcha.getClient(
       withSiteKey: "KEY_ID",
       withTimeout: 15000
     ) { client, error in
       guard let client = client else {
           print("RecaptchaClient creation error: \(error).")
         return
       }
       self.recaptchaClient = client
     }
   

2. Définissez un délai d'inactivité lors de l'appel de execute.

     Task {
       do {
         let token = try await recaptchaClient.execute(
           withAction: RecaptchaAction.login,
           withTimeout: 10000)
         print(token)
       } catch let error as RecaptchaError {
         print(error.errorMessage)
       }
     }
   

   Si la version minimale de l'OS de votre application est antérieure à la version 13, utilisez plutôt une fermeture finale:

     recaptchaClient.execute(
       withAction: RecaptchaAction.login,
       withTimeout: 10000
     ) { token, error in
       if let token = token {
         print(token)
       } else {
         print(error)
       }
     }
   

Objective-C

1. Définissez un délai d'inactivité lors de l'appel de getClient.

     [Recaptcha getClientWithSiteKey:@"KEY_ID"
                 withTimeout:15000.0
                  completion:^void(RecaptchaClient *recaptchaClient, NSError *error) {
                    if (!recaptchaClient) {
                      NSLog(@"%@", (RecaptchaError *)error.errorMessage);
                      return;
                    }
                    self->_recaptchaClient = recaptchaClient;
                  }];
   

2. Définissez un délai d'inactivité lors de l'appel de execute.

     [recaptchaClient execute:RecaptchaAction.login
         witTimeout:10000.0
         completion:^void(NSString* _Nullable  token, NSError* _Nullable error) {
       if (!token) {
         NSLog (@"%@", (RecaptchaError *)error.errorMessage);
         return;
       }
       NSLog (@"%@", token);
     }];
   

Documentation de référence de l'API

Pour en savoir plus sur l'API reCAPTCHA pour iOS, consultez RecaptchaEnterprise.

Étapes suivantes

• Pour évaluer le jeton de réponse reCAPTCHA, créez une évaluation.

  Remarque :Les jetons de réponse reCAPTCHA sont évalués et annotés à partir de votre serveur backend, et non de l'appareil mobile.