Integra reCAPTCHA con le app per iOS

Questa pagina spiega come integrare reCAPTCHA 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 della casella di controllo visiva (Non sono un robot) non è disponibile per le app mobile iOS. Puoi invece implementare la tua strategia di applicazione su più livelli, ad esempio un flusso MFA per fornire un percorso di riscatto 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 nelle applicazioni o negli 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.

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.

        Vai a reCAPTCHA

     2. Nell'elenco delle chiavi reCAPTCHA, tieni il puntatore sulla chiave che vuoi copiare, quindi 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 le informazioni 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 iOS vuota.

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

   CocoaPods

   1. Scarica e installa CocoaPods.

   2. Crea un Podfile e aggiungi le seguenti righe al 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.1"
        ...
      
      end
      

   3. Installa le dipendenze richieste eseguendo pod update.

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

   Gestore pacchetti Swift

   1. In XCode, seleziona File > Add Packages (File > Aggiungi pacchetti) e inserisci il seguente URL nel campo Cerca o Inserisci URL del 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 Personal Access Token (Token di accesso personale) deve includere gli ambiti elencati nella finestra di dialogo XCode Sign In (Accesso a XCode).

      Xcode installa l'SDK e le sue dipendenze obbligatorie.

   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 sue dipendenze come xcframeworks, scarica il client.

      Nota: aggiungi tutti i file binari come xcframeworks statico.

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 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 build > Incorpora sempre le librerie standard di Swift e verifica che l'opzione sia impostata su Yes.

Integra reCAPTCHA con la tua app per iOS

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

Nota: la latenza dell'SDK reCAPTCHA può essere elevata, quindi ti consigliamo di chiamare Recaptcha.getClient(siteKey:) e execute() il prima possibile, ad esempio durante il caricamento dell'app. Non devi bloccare gli elementi UI 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:

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

   Naviga 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 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 un'istanza per 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 e attivare execute().

   Naviga con lo storyboard

   1. Nello storyboard, crea un pulsante.
   2. Creare 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 dell'applicazione è precedente alla 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)
        }
      }
      

   Naviga 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 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. Nello storyboard, crea un pulsante.
   2. Creare 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:

      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 la tua 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, procedi nel seguente modo:

      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 build Xcode, fai clic su Pulisci cartella build nel menu Product (Prodotto).

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

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

   5. Osserva la finestra di output del 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 ciascuna API.

Nota: per garantire coerenza, viene utilizzato un timeout predefinito di 10 secondi per le API getClient e execute.

Swift

1. Imposta il timeout durante la chiamata a 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 è precedente 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 durante la chiamata a 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 è precedente 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 durante la chiamata a 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 durante la chiamata a 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, 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 tuo server di backend, non dal dispositivo mobile.