Integrare 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 interfacce utente delle app, il test reCAPTCHA visivo con casella di controllo (Non sono un robot) non è disponibile per le app mobile iOS. In alternativa, puoi implementare una strategia di applicazione a più livelli, ad esempio un flusso MFA per fornire un percorso di utilizzo alternativo per il traffico sospetto.

L'SDK utilizza la reflection 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.

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 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 consoleGoogle Cloud , segui questi passaggi:

      1. Vai alla pagina reCAPTCHA.

        Vai a reCAPTCHA

      2. Nell'elenco delle chiavi reCAPTCHA, tieni il puntatore del mouse sulla chiave che vuoi copiare e poi 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. Disporre di 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 l'ultima versione di Xcode e crea una nuova applicazione iOS con una sola visualizzazione 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:

      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.8.0-beta01"
  ...

end

    3. Installa le dipendenze richieste eseguendo pod update.

    Swift Package Manager

    1. In Xcode, seleziona File > Add Packages (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 creato seguendo le istruzioni di GitHub. Il token di accesso personale deve avere gli ambiti elencati nella finestra di dialogo Accesso 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 xcframework, scarica il client.

Integra reCAPTCHA con la tua 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. Se la tua app è scritta in Objective-C, crea un file Swift fittizio e includi il seguente import 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 > Build Settings > Always Embed Swift Standard Libraries e verifica che l'opzione sia impostata su Yes.

    3. Aggiorna ViewController.h.

      #import <RecaptchaEnterprise/RecaptchaEnterprise.h>

@interface ViewController : UIViewController
@property (strong, atomic) RecaptchaClient *recaptchaClient;
@end

    4. 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 chiamata onCreate() di una classe Application personalizzata. Non devi bloccare gli elementi UI 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 lo snippet di codice seguente:

      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. 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:

      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 App Attest di Apple come parte del suo 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 di Xcode, nel menu Prodotto, fai clic su Pulisci cartella build.

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

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

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

Migrazione dal metodo API 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, quest'ultimo continua a riprovare e viene inizializzato correttamente quando viene acquisita una rete.

Se chiami execute(timeout) e il client non è ancora pronto, tenta di inizializzare 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.

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

Gestisci gli errori

Se la tua app non riesce a comunicare correttamente con il servizio reCAPTCHA, il problema potrebbe essere dovuto a un errore dell'API. Devi aggiungere una logica nella tua app per gestire correttamente questi errori.

Per maggiori dettagli sulle mitigazioni per gli errori API comuni, 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.