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 le tue strategia di applicazione su più livelli, ad esempio un flusso MFA per fornire un’alternativa di utilizzo in caso di 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 di 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, tieni il puntatore sulla 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 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.6.0" ... 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 > 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 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 relative 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 dummy e includi la seguente 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 Target > Impostazioni build > Incorpora sempre Swift Librerie standard 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:

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

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

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

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 elementi UI nell'SDK reCAPTCHA.

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

Naviga con lo storyboard

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

Richiama il metodo execute() che passa un'azione Login per restituire un 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 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)
  }
}

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 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 l'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 pulire l'ambiente di build Xcode, nel menu Product (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 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 method al metodo fetchClient

Il metodo fetchClient restituisce un RecaptchaClient che ritenta 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.

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

Naviga 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

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

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 correttamente, è possibile che si sia verificato un errore nell'API. Devi aggiungere nella tua app per gestire agevolmente questi errori.

Per maggiori 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 tuo backend. non dal dispositivo mobile.

Integrare reCAPTCHA con le app per iOS

Prima di iniziare

Prepara l'ambiente iOS

CocoaPods

Gestore pacchetti Swift

Flutter

React Native

Download diretto

Configura l'app

Swift

Objective-C

Integrare reCAPTCHA con l'app per iOS

Swift con Storyboard

Swift con SwiftUI

Objective-C

Naviga con lo storyboard

Naviga con SwiftUI

Objective-C

Migrazione dall'API method al metodo fetchClient

Naviga con lo storyboard

Naviga con SwiftUI

Objective-C

Impostare un timeout per le chiamate API

Swift

Objective-C

Gestire gli errori

Riferimento API

Passaggi successivi