Questa pagina è stata tradotta dall'API Cloud Translation.

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 autenticazione a due fattori 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.

Prima di iniziare

Imposta l'SDK minimo della tua app su iOS 12 o crea una nuova app mobile.
Prepara l'ambiente per reCAPTCHA.
Crea una chiave reCAPTCHA per la piattaforma per app per iOS.

In alternativa, puoi copiare l'ID di una chiave reCAPTCHA per iOS esistente 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, 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.
Avere un account GitHub.
Leggi le informazioni sulla privacy di Apple.

Prepara l'ambiente iOS

Per preparare l'ambiente di sviluppo:

Scarica e installa la versione più recente di Xcode e crea una nuova applicazione iOS con una singola visualizzazione vuota.
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 > Add Packages (File > Aggiungi pacchetti) e inserisci 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 sue dipendenze obbligatorie.
Flutter
Per istruzioni dettagliate sull'utilizzo di reCAPTCHA tramite Flutter, consulta la documentazione di Flutter.

React Native
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 statici.

Configura l'app

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

Per configurare l'app, aggiungi i seguenti file:

Swift

Se la tua app è scritta in Swift, includi la seguente importazione:
```
 import RecaptchaEnterprise
```

Objective-C

Se la tua app è scritta in Objective-C, crea un file Swift fittizio e includi la dopo l'importazione per assicurarti che Xcode possa trovare e collegare le librerie Swift.
```
import Foundation
```
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.

Integra reCAPTCHA con la tua app per iOS

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

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

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 dell'applicazione è precedente alla 13, utilizza un 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
    }
  }
}

Naviga con SwiftUI

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

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

Aggiorna ViewController.h.

#import <RecaptchaEnterprise/RecaptchaEnterprise.h>

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

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

Il completamento dell'inizializzazione dell'SDK può richiedere diversi secondi. Per ridurre questa latenza, inizializza il client il prima possibile, ad esempio durante Chiamata onCreate() di una classe Application personalizzata. Non devi bloccare gli elementi dell'interfaccia utente nell'SDK reCAPTCHA.

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

Swift con Storyboard

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

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

Naviga con SwiftUI

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

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

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

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 completato, ad esempio in condizioni di rete lente o se è in attesa l'inizializzazione in background. Assicurati che le chiamate execute() non blocchino un evento dell'interfaccia utente, ad esempio la pressione di un pulsante.

Testa la tua applicazione:
1. reCAPTCHA utilizza AppAttest 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:
  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 creato in precedenza.
5. Osserva la finestra di output del debug per un token reCAPTCHA (stringa alfanumerica), che viene restituita se l'integrazione va a buon fine.

Migrazione dall'API del metodo al metodo fetchClient

Il metodo fetchClient restituisce un RecaptchaClient che ritenta l'inizializzazione in caso di errori di rete. Se l'app non presenta l'accesso alla rete quando il client viene creato, il client continua a riprovare viene inizializzata 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.

Naviga con lo 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 il metodo proprietà withTimeout.

Swift

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

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

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.

Integrare reCAPTCHA con le app per iOS

Prima di iniziare

Prepara l'ambiente iOS

CocoaPods

Swift Package Manager

Flutter

React Native

Download diretto

Configura l'app

Swift

Objective-C

Integra reCAPTCHA con la tua app per iOS

Swift con Storyboard

Naviga con SwiftUI

Objective-C

Swift con Storyboard

Naviga con SwiftUI

Objective-C

Migrazione dall'API del metodo al metodo fetchClient

Naviga con lo storyboard

Swift con SwiftUI

Objective-C

Impostare un timeout per le chiamate API

Swift

Objective-C

Gestire gli errori

Riferimento API

Passaggi successivi