Integrare reCAPTCHA con le app per iOS

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

A causa della variabilità 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. In alternativa, puoi implementare la tua strategia di applicazione a più livelli, ad esempio un flusso di MFA per fornire un percorso di riscatto alternativo per il traffico sospetto.

L'SDK utilizza la riflessione e il codice dinamico per consentire l'aggiornamento e il perfezionamento del sistema di rilevamento nelle applicazioni o negli SDK già implementati. Per evitare interferenze con l'applicazione, l'insieme di classi disponibili nel sistema è limitato a un elenco attentamente controllato.

Importante: prendi nota delle norme relative al ritiro e al ritiro dal servizio e pianifica di eseguire l'upgrade dell'SDK regolarmente.

Prima di iniziare

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

2. Prepara l'ambiente per reCAPTCHA.

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

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

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

     1. Vai alla pagina reCAPTCHA.

        Vai a reCAPTCHA

     2. Nell'elenco delle chiavi reCAPTCHA, posiziona il cursore del mouse sopra la chiave che vuoi copiare e fai clic su .
   • Per copiare l'ID di una chiave esistente utilizzando l'API REST, utilizza 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 iOS con una singola visualizzazione vuota.

2. Scarica l'SDK utilizzando una delle seguenti opzioni:

   CocoaPods

   1. Scarica e installa CocoaPods.

   2. Crea un Podfile e aggiungi le seguenti righe:

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

   3. Installa le dipendenze richieste eseguendo pod update.

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

   Swift Package Manager

   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 avere gli ambiti elencati nella finestra di dialogo Accedi a Xcode.

      Xcode installa l'SDK e le relative dipendenze richieste.

   Flutter

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

   ReactNative

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

   Download diretto

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

      Nota: aggiungi tutti i binari come xcframeworks statici.

Configura l'app

Puoi scrivere le tue app in Swift o Objective-C.

Per configurare l'app, aggiungi i seguenti file:

Swift

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

    import RecaptchaEnterprise
   

Objective-C

1. Se la tua app è scritta in Objective-C, crea un file Swift dummy 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 Destinazione > Impostazioni di compilazione > Incorpora sempre le librerie standard di Swift e verifica che l'opzione sia impostata su Yes.

Integrare reCAPTCHA con l'app per iOS

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

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

   Swift con Storyboard

   1. Aggiorna ViewController.swift.

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

      Se la versione minima del sistema operativo della tua applicazione è inferiore a 13, utilizza una chiusura finale:

      import RecaptchaEnterprise
      
      class ViewController: UIViewController {
        var recaptchaClient: RecaptchaClient?
      
        override func viewDidLoad() {
          super.viewDidLoad()
          Recaptcha.fetchClient(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 {
              self.recaptchaClient = try await Recaptcha.fetchClient(withSiteKey: "KEY_ID")
            } catch let error as RecaptchaError {
               print("RecaptchaClient creation error: \(String(describing: error.errorMessage)).")
            }
          }
        }
      }
      

      Se la versione minima del sistema operativo della tua applicazione è inferiore a 13, utilizza una chiusura finale:

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

   2. Crea un'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 fetchClientWithSiteKey:@"KEY_ID"
            completion:^void(RecaptchaClient* recaptchaClient, NSError* error) {
              if (!recaptchaClient) {
                NSLog(@"%@", (RecaptchaError *)error.errorMessage);
                return;
              }
              self->_recaptchaClient = recaptchaClient;
            }
      ];
      @end
      

   L'inizializzazione dell'SDK può richiedere diversi secondi. Per ridurre questa latenza, inizializza il client il prima possibile, ad esempio durante la onCreate() chiamata di un Application personalizzato. Non devi bloccare gli elementi dell'interfaccia utente nell'SDK reCAPTCHA.

2. Crea un pulsante per chiamare reCAPTCHA e attivare execute().

   Swift con Storyboard

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

   3. Chiama il metodo execute() passando 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 della tua applicazione è inferiore a 13, utilizza 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 della tua applicazione è inferiore a 13, utilizza 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. Nel storyboard, crea un pulsante.
   2. Crea un'azione in ViewController collegata al pulsante che hai creato.

   3. Chiama il metodo execute() passando un'azione Login per restituire un token reCAPTCHA:

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

   L'API execute del client può richiedere diversi secondi per essere completata, ad esempio in condizioni di rete lente o se è in attesa del completamento dell'inizializzazione in background. Assicurati che le chiamate execute() non blocchino un evento dell'interfaccia utente, ad esempio la pressione di un pulsante.

3. Testa l'applicazione:

   1. reCAPTCHA 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 ripulire l'ambiente di build di 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 che hai creato in precedenza.

   5. Nella finestra di output di debug, controlla se è presente un token reCAPTCHA (stringa alfanumerica), che viene restituito se l'integrazione è riuscita.

Migrazione dall'API method al metodo fetchClient

Il metodo fetchClient restituisce un RecaptchaClient che riprova l'inizializzazione in caso di errori di rete. Se l'app non ha accesso alla rete quando viene creato il client, il client continua a riprovare e si inizializza correttamente quando viene acquisita una rete.

Se chiami execute(timeout) e il client non è ancora pronto, tenta di inizializzarsi prima di restituire un token o un RecaptchaErrorCode.

L'esempio seguente mostra come eseguire la migrazione da getClient a fetchClient.

Swift con Storyboard

// Migrate from getClient
func initializeWithGetClient() {
  Task {
    do {
      self.recaptchaClient = try await Recaptcha.getClient(withSiteKey: "KEY_ID")
    } catch let error as RecaptchaError {
        print("RecaptchaClient creation error: \(String(describing: error.errorMessage)).")
    }
  }
}

// Migrate to fetchClient
func initializeWithFetchClient() {
  Task {
    do {
      self.recaptchaClient = try await Recaptcha.fetchClient(withSiteKey: "KEY_ID")
    } catch let error as RecaptchaError {
        print("RecaptchaClient creation error: \(String(describing: error.errorMessage)).")
    }
  }
}

Se la versione minima del sistema operativo della tua applicazione è inferiore a 13, utilizza una chiusura finale:

// Migrate from getClient
override func initializeWithGetClient() {
  Recaptcha.getClient(withSiteKey: "KEY_ID") { client, error in
    guard let client = client else {
        print("RecaptchaClient creation error: \(error).")
      return
    }
    self.recaptchaClient = client
  }
}

// Migrate to fetchClient
override func initializeWithFetchClient() {
  Recaptcha.fetchClient(withSiteKey: "KEY_ID") { client, error in
    guard let client = client else {
        print("RecaptchaClient creation error: \(error).")
      return
    }
    self.recaptchaClient = client
  }
}

Swift con SwiftUI

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

// Migrate to fetchClient
initializeWithFetchClient() {
    Task {
    do {
      self.recaptchaClient = try await Recaptcha.fetchClient(withSiteKey: "KEY_ID")
    } catch let error as RecaptchaError {
        print("RecaptchaClient creation error: \(String(describing: error.errorMessage)).")
    }
  }
}

Se la versione minima del sistema operativo della tua applicazione è inferiore a 13, utilizza una chiusura finale:

// Migrate from getClient
func initializeWithGetClient() {
  super.viewDidLoad()
  Recaptcha.getClient(withSiteKey: "KEY_ID") { client, error in
    guard let client = client else {
        print("RecaptchaClient creation error: \(error).")
      return
    }
    self.recaptchaClient = client
  }
}

// Migrate to fetchClient
func initializeWithFetchClient() {
  super.viewDidLoad()
  Recaptcha.fetchClient(withSiteKey: "KEY_ID") { client, error in
    guard let client = client else {
        print("RecaptchaClient creation error: \(error).")
      return
    }
    self.recaptchaClient = client
  }
}

Objective-C

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

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

Impostare un timeout per le chiamate API

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

Nota: per coerenza, viene utilizzato un timeout predefinito di 10 secondi.

Swift

1. Imposta il timeout quando chiami 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 della tua applicazione è inferiore a 13, utilizza invece 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 quando chiami 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);
     }];
   

Gestire gli errori

Se la tua app non riesce a comunicare con il servizio reCAPTCHA, il motivo potrebbe essere che l'API ha rilevato un errore. Devi aggiungere la logica all'app per gestire in modo appropriato questi errori.

Per ulteriori dettagli sulle mitigazioni per gli errori comuni dell'API, consulta RecaptchaErrorCode.

Riferimento API

Per un riferimento completo dell'API reCAPTCHA per iOS, consulta 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.