reCAPTCHA in iOS-Apps einbinden

Auf dieser Seite wird erläutert, wie Sie reCAPTCHA in Ihre iOS-App einbinden.

Aufgrund der vielfältigen Mobilgeräte in Bezug auf Bildschirmgröße, Leistung und UIs der Anwendungen ist die visuelle reCAPTCHA-Abfrage mit dem Kästchen Ich bin kein Roboter für mobile iOS-Apps nicht verfügbar. Stattdessen können Sie eine eigene mehrstufige Erzwingungsstrategie implementieren, z. B. einen MFA-Ablauf, um einen alternativen Einlösungspfad für verdächtigen Traffic bereitzustellen.

Das SDK verwendet Reflection und dynamischen Code, um das Erkennungssystem in bereits bereitgestellten Anwendungen oder SDKs zu aktualisieren und zu optimieren. Um Beeinträchtigungen der Anwendung zu vermeiden, ist die Menge der im System verfügbaren Klassen auf eine sorgfältig kontrollierte Liste beschränkt.

Hinweise

1. Legen Sie die Mindest-SDK-Version Ihrer App auf iOS 12 fest oder erstellen Sie eine neue mobile App.

2. Umgebung für reCAPTCHA vorbereiten

3. Erstellen Sie einen reCAPTCHA-Schlüssel für die iOS-App-Plattform.

   Alternativ können Sie die ID eines vorhandenen reCAPTCHA-Schlüssels für iOS kopieren. Führen Sie dazu einen der folgenden Schritte aus:

   • So kopieren Sie die ID eines vorhandenen Schlüssels aus der Google Cloud -Konsole:

     1. Rufen Sie die Seite reCAPTCHA auf.

        Zu reCAPTCHA

     2. Halten Sie in der Liste der reCAPTCHA-Schlüssel den Mauszeiger auf den Schlüssel, den Sie kopieren möchten, und klicken Sie dann auf content_copy .
   • Verwenden Sie die Methode projects.keys.list, um die ID eines vorhandenen Schlüssels mithilfe der REST API zu kopieren.
   • Verwenden Sie den Befehl gcloud recaptcha keys list, um die ID eines vorhandenen Schlüssels mit der gcloud CLI zu kopieren.

4. Sie benötigen ein GitHub-Konto.

5. Datenschutzdetails von Apple

iOS-Umgebung vorbereiten

So bereiten Sie die Entwicklungsumgebung vor:

1. Laden Sie die neueste Version von Xcode herunter und installieren Sie sie. Erstellen Sie dann eine neue, leere iOS-Einzelansichts-App.

2. Laden Sie das SDK mit einer der folgenden Methoden herunter:

   CocoaPods

   1. Laden Sie CocoaPods herunter und installieren Sie es.

   2. Erstellen Sie eine Podfile-Datei und fügen Sie ihr die folgenden Zeilen hinzu:

      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. Installieren Sie die erforderlichen Abhängigkeiten,. Dazu führen Sie pod update aus.

   Swift Package Manager

   1. Wählen Sie in Xcode File > Add Packages aus und geben Sie die folgende URL in das Feld Search (Suchen) oder Enter Package URL (Paket-URL eingeben) ein: https://github.com/GoogleCloudPlatform/recaptcha-enterprise-mobile-sdk

   2. Geben Sie im Dialogfeld Xcode die folgenden Details ein:

      • GitHub-Nutzername
      • Ein persönliches Zugriffstoken, das Sie gemäß der Anleitung von GitHub erstellt haben. Das persönliche Zugriffstoken muss die im Dialogfeld XCode Sign In (XCode-Anmeldung) aufgeführten Bereiche haben.

      Xcode installiert das SDK und die erforderlichen Abhängigkeiten.

   Flutter

   Eine ausführliche Anleitung zur Verwendung von reCAPTCHA über Flutter finden Sie in der Flutter-Dokumentation.

   ReactNative

   Eine ausführliche Anleitung zur Verwendung von reCAPTCHA über React Native finden Sie in der React Native-Dokumentation.

   Direkter Download

   1. Wenn Sie das SDK und seine Abhängigkeiten als XCFrameworks herunterladen möchten, laden Sie den Client herunter.

reCAPTCHA in Ihre iOS-App einbinden

Führen Sie folgende Schritte in Xcode aus, um reCAPTCHA in Ihre iOS-App einzubinden:

1. Aktualisieren Sie die App mit dem folgenden Code, um das SDK mit dem von Ihnen erstellten reCAPTCHA-Schlüssel (KEY_ID) zu instanziieren:

   Swift mit Storyboard

   1. ViewController.swift aktualisieren.

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

      Wenn die Mindestversion des Betriebssystems Ihrer Anwendung niedriger als 13 ist, verwenden Sie stattdessen einen nachgestellten Closure:

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

   1. Erstellen Sie eine ViewModel-Klasse.

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

      Wenn die Mindestversion des Betriebssystems Ihrer Anwendung niedriger als 13 ist, verwenden Sie stattdessen einen nachgestellten Closure:

      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. Instanziieren Sie 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. Wenn Ihre App in Objective-C geschrieben ist, erstellen Sie eine Dummy-Swift-Datei und fügen Sie den folgenden Import ein, damit Xcode die Swift-Bibliotheken finden und verknüpfen kann.

      import Foundation
      

   2. Damit der Swift-Code richtig verknüpft wird, gehen Sie zu Ziel > Build-Einstellungen > Swift-Standardbibliotheken immer einbetten und prüfen Sie, ob die Option auf Yes festgelegt ist.

   3. ViewController.h aktualisieren.

      #import <RecaptchaEnterprise/RecaptchaEnterprise.h>
      
      @interface ViewController : UIViewController
      @property (strong, atomic) RecaptchaClient *recaptchaClient;
      @end
      

   4. ViewController.m aktualisieren.

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

   Die Initialisierung des SDK kann mehrere Sekunden dauern. Um diese Latenz zu verringern, sollten Sie den Client so früh wie möglich initialisieren, z. B. während des onCreate()-Aufrufs einer benutzerdefinierten Application-Klasse. UI-Elemente sollten nicht auf das reCAPTCHA SDK warten.

2. Erstellen Sie eine Schaltfläche, um reCAPTCHA aufzurufen und execute() auszulösen.

   Swift mit Storyboard

   1. Erstellen Sie im Storyboard eine Schaltfläche.
   2. Erstellen Sie in ViewController eine Aktion, die mit der von Ihnen erstellten Schaltfläche verknüpft ist.

   3. Rufen Sie die execute()-Methode auf und übergeben Sie eine Login-Aktion, um ein reCAPTCHA-Token mit folgendem Code-Snippet zurückzugeben:

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

      Wenn die Mindestversion des Betriebssystems Ihrer Anwendung niedriger als 13 ist, verwenden Sie stattdessen einen nachgestellten Closure:

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

   1. Aktualisieren Sie „ViewModel.swift“ mit dem Ausführungscode:

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

      Wenn die Mindestversion des Betriebssystems Ihrer Anwendung niedriger als 13 ist, verwenden Sie stattdessen einen nachgestellten Closure:

      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. Aktualisieren Sie 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. Erstellen Sie im Storyboard eine Schaltfläche.
   2. Erstellen Sie in ViewController eine Aktion, die mit der von Ihnen erstellten Schaltfläche verknüpft ist.

   3. Rufen Sie die execute()-Methode auf und übergeben Sie eine Login-Aktion, um ein reCAPTCHA-Token zurückzugeben:

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

   Die execute API des Clients kann mehrere Sekunden dauern, z. B. bei langsamen Netzwerkbedingungen oder wenn sie auf den Abschluss der Hintergrundinitialisierung wartet. Achten Sie darauf, dass die execute()-Aufrufe kein UI-Ereignis blockieren, z. B. das Drücken einer Schaltfläche.

3. Ihre Anwendung testen:

   1. reCAPTCHA verwendet App Attest von Apple als Teil seiner Erkennungs-Engine. Wenn Sie keinen Testschlüssel mit einer festen Punktzahl für die lokale Entwicklung verwenden möchten, gehen Sie so vor:

      1. Fügen Sie Ihrer App in Xcode die Funktion App Attest hinzu.

      2. Legen Sie in der Datei .entitlements Ihres Projekts die App Attest-Umgebung auf production fest.

   2. Wenn Sie Ihre Xcode-Build-Umgebung bereinigen möchten, klicken Sie im Menü Produkt auf Build-Ordner bereinigen.

   3. Klicken Sie zum Ausführen der Anwendung im Menü Produkt auf Ausführen.

   4. Klicken Sie in der geladenen Anwendung auf die Schaltfläche, die Sie zuvor erstellt haben.

   5. Beobachten Sie das Debug-Ausgabefenster für ein reCAPTCHA-Token (alphanumerischer String), das zurückgegeben wird, wenn die Integration erfolgreich ist.

Von der Methode „API“ zur Methode „fetchClient“ migrieren

Die fetchClient-Methode gibt ein RecaptchaClient zurück, das die Initialisierung bei Netzwerkfehlern wiederholt. Wenn die App beim Erstellen des Clients keinen Netzwerkzugriff hat, wird der Vorgang wiederholt und der Client wird initialisiert, sobald ein Netzwerk verfügbar ist.

Wenn Sie execute(timeout) aufrufen und der Client noch nicht bereit ist, wird versucht, ihn zu initialisieren, bevor ein Token oder ein RecaptchaErrorCode zurückgegeben wird.

Das folgende Beispiel zeigt, wie Sie von getClient zu fetchClient migrieren.

// 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)).")
    }
  }
}

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

// 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)).")
    }
  }
}

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

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

Zeitüberschreitung für API-Aufrufe festlegen

Mit der Property withTimeout können Sie einen Zeitüberschreitungswert für die execute-APIs angeben.

Fehler verarbeiten

Wenn Ihre App nicht mit dem reCAPTCHA-Dienst kommunizieren kann, ist möglicherweise ein API-Fehler aufgetreten. Sie müssen Ihrer App eine Logik hinzufügen, um solche Fehler ordnungsgemäß zu bearbeiten.

Weitere Informationen zu den Maßnahmen für häufige API-Fehler finden Sie unter RecaptchaErrorCode.

API-Referenz

Eine vollständige Referenz zur reCAPTCHA API für iOS finden Sie unter RecaptchaEnterprise.

Nächste Schritte

• Um das reCAPTCHA-Antworttoken zu bewerten, erstellen Sie eine Bewertung.