Integra reCAPTCHA Enterprise con le app per iOS

Questa pagina spiega come integrare reCAPTCHA Enterprise nella tua app per iOS.

A causa della variazione dei dispositivi mobili in termini di dimensioni dello schermo, prestazioni e UI delle app, la verifica reCAPTCHA con casella di controllo visiva (Non sono un robot) non è disponibile per le app mobile per iOS. Puoi invece implementare la tua strategia di applicazione a più livelli, ad esempio un flusso MFA per fornire un percorso di utilizzo alternativo per il traffico sospetto.

Nota: l'SDK utilizza la riflessione e il codice dinamico per consentire l'aggiornamento e il perfezionamento del sistema di rilevamento in applicazioni o SDK già di cui è stato eseguito il deployment. Per evitare interferenze con l'applicazione, l'insieme di classi disponibili nel sistema è limitato a un elenco attentamente controllato.

Prima di iniziare

1. Imposta l'SDK minimo della tua app su iOS 11 o crea una nuova app mobile.

2. Prepara l'ambiente per reCAPTCHA Enterprise.

3. Crea una chiave reCAPTCHA per la piattaforma di app per iOS.

   In alternativa, puoi copiare l'ID di una chiave reCAPTCHA esistente per iOS eseguendo uno dei seguenti passaggi:

   • Per copiare l'ID di una chiave esistente dalla console Google Cloud, segui questi passaggi:

     1. Vai alla pagina reCAPTCHA Enterprise.

        Vai a reCAPTCHA Enterprise

     2. Nell'elenco delle chiavi reCAPTCHA, tieni il puntatore del mouse sulla chiave che vuoi copiare e fai clic su .
   • Per copiare l'ID di una chiave esistente con l'API REST, usa il metodo projects.keys.list.
   • Per copiare l'ID di una chiave esistente utilizzando gcloud CLI, utilizza il comando gcloud recaptcha keys list.

4. Avere un account GitHub.

5. Leggi i dettagli sulla privacy di Apple.

Prepara l'ambiente iOS

Per preparare l'ambiente di sviluppo:

1. Scarica e installa la versione più recente di Xcode e crea una nuova applicazione di visualizzazione singola per iOS vuota.

2. Scarica l'SDK utilizzando uno dei seguenti strumenti:

   CocoaPods

   1. Scarica e installa CocoaPods.

   2. Crea un Podfile e aggiungi le seguenti righe al file:

      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"
        ...
      
      end
      

   3. Installa le dipendenze richieste eseguendo pod update.

      Nota: l'esecuzione di pod clone non installa le dipendenze richieste.

   Gestione pacchetti Swift

   1. In XCode, seleziona File > Aggiungi pacchetti e inserisci il seguente URL nel campo Cerca o Inserisci URL pacchetto: https://github.com/GoogleCloudPlatform/recaptcha-enterprise-mobile-sdk

   2. Nella finestra di dialogo XCode, inserisci i seguenti dettagli:

      • Nome utente GitHub.
      • Un token di accesso personale che hai creato seguendo le istruzioni di GitHub. Il token di accesso personale deve includere gli ambiti elencati nella finestra di dialogo Accesso XCode.

      Xcode installa l'SDK e le dipendenze richieste.

   Flutter

   Per istruzioni dettagliate sull'utilizzo di reCAPTCHA Enterprise tramite Flutter, consulta la documentazione di Flutter.

   ReactNative

   Per istruzioni dettagliate sull'utilizzo di reCAPTCHA Enterprise tramite React Native, consulta la documentazione relativa a React Native.

   Download diretto

   1. Se vuoi scaricare l'SDK e le sue dipendenze come xcframeworks, scarica il client.

      Nota: aggiungi tutti i file binari come xcframeworks statici.

Configura l'app

Puoi scrivere le app in Swift o Objective-C.

Per configurare l'app, aggiungi i seguenti file nell'app:

Swift

1. Se la tua app è scritta in Swift, includi la seguente importazione:

   #import RecaptchaEnterprise
   

Objective-C

1. Se l'app è scritta in Objective-C, crea un file Swift fittizio e includi la seguente importazione per assicurarti che Xcode possa trovare e collegare le librerie Swift.

   import Foundation
   

2. Per assicurarti che il codice Swift sia collegato correttamente, vai a Target > Impostazioni di build > Incorpora sempre le librerie standard Swift e verifica che l'opzione sia impostata su Yes.

Integra reCAPTCHA Enterprise con la tua app per iOS

Per integrare reCAPTCHA Enterprise con la tua app per iOS, segui questi passaggi in Xcode:

Nota: la latenza dell'SDK reCAPTCHA può essere elevata, quindi consigliamo di chiamare Recaptcha.getClient(siteKey:) e execute() il prima possibile, ad esempio al caricamento dell'app. Non devi bloccare gli elementi dell'interfaccia utente nell'SDK reCAPTCHA.

1. Per creare un'istanza dell'SDK con la chiave reCAPTCHA (KEY_ID) che hai creato, aggiorna l'app con il seguente codice:

   Salta con lo storyboard

   1. Aggiorna ViewController.swift.

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

      Se la versione minima del sistema operativo dell'applicazione è precedente alla 13, utilizza invece una chiusura 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 con SwiftUI

   1. Crea un corso ViewModel.

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

      Se la versione minima del sistema operativo dell'applicazione è precedente alla 13, utilizza invece una chiusura 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. Crea l'istanza di ViewModel in 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. Aggiorna ViewController.h.

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

   2. Aggiorna 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. Crea un pulsante per chiamare reCAPTCHA Enterprise e attivare execute().

   Salta con lo storyboard

   1. Nella griglia, crea un pulsante.
   2. Crea un'azione in ViewController collegata al pulsante che hai creato.

   3. Chiama il metodo execute() che trasmette un'azione Login per restituire un token reCAPTCHA utilizzando il seguente snippet di codice:

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

      Se la versione minima del sistema operativo dell'applicazione è precedente alla 13, utilizza invece una chiusura 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 con SwiftUI

   1. Aggiorna ViewModel.swift con il codice di esecuzione:

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

      Se la versione minima del sistema operativo dell'applicazione è precedente alla 13, utilizza invece una chiusura 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. Aggiorna 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. Crea un pulsante nello storyboard.
   2. Crea un'azione in ViewController collegata al pulsante che hai creato.

   3. Chiama il metodo execute() che trasmette un'azione Login per restituire un token reCAPTCHA utilizzando il seguente snippet di codice:

      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. Testa l'applicazione:

   1. reCAPTCHA Enterprise utilizza AppAttest di Apple come parte del proprio motore di rilevamento. Se non prevedi di utilizzare una chiave di test con un punteggio fisso per lo sviluppo locale:

      1. In Xcode, aggiungi la funzionalità App Attest alla tua app.

      2. Nel file .entitlements del progetto, imposta l'ambiente App Attest su production.

   2. Per pulire l'ambiente di compilazione Xcode, nel menu Prodotto, fai clic su Pulisci cartella Build.

   3. Per eseguire l'applicazione, fai clic su Esegui nel menu Prodotto.

   4. Nell'applicazione caricata, fai clic sul pulsante creato in precedenza.

   5. Osserva la finestra di output di debug per verificare la presenza di un token reCAPTCHA (stringa alfanumerica), che viene restituito se l'integrazione ha esito positivo.

Imposta un timeout per le chiamate API

Puoi specificare un valore di timeout per le API getClient e execute utilizzando la proprietà withTimeout di ogni API.

Nota: per la coerenza viene utilizzato un timeout predefinito di 10 secondi sia per le API getClient che per execute.

Swift

1. Imposta il timeout per la chiamata al numero 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)).")
         }
       }
   

   Se la versione minima del sistema operativo dell'applicazione è inferiore alla 13, utilizza una chiusura 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. Imposta il timeout per la chiamata al numero execute.

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

   Se la versione minima del sistema operativo dell'applicazione è inferiore alla 13, utilizza una chiusura finale:

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

Objective-C

1. Imposta il timeout per la chiamata al numero 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. Imposta il timeout per la chiamata al numero 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);
     }];
   

Riferimento API

Per un riferimento completo dell'API reCAPTCHA per iOS, vedi RecaptchaEnterprise.

Passaggi successivi

• Per valutare il token di risposta reCAPTCHA, crea una valutazione.

  Nota: i token di risposta reCAPTCHA vengono valutati e annotati dal server di backend, non dal dispositivo mobile.