reCAPTCHA in iOS-Apps einbinden

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

Aufgrund der Vielfalt der Mobilgeräte in Bezug auf Bildschirmgröße, Leistung und UIs der Apps ist die visuelle reCAPTCHA-Abfrage mit Kästchen (Ich bin kein Roboter) für iOS-Apps nicht verfügbar. Sie können stattdessen Ihre eigene abgestufte Durchsetzungsstrategie implementieren, z. B. einen MFA-Ablauf, um bei verdächtigem Traffic einen alternativen Ablauf für die Gutscheineinlösung bereitzustellen.

Das SDK nutzt 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, sind die im System verfügbaren Klassen auf eine sorgfältig kontrollierte Liste beschränkt.

Wichtig: Beachten Sie die Richtlinien zur Einstellung und Außerbetriebnahme und planen Sie regelmäßige Updates des SDKs.

Hinweise

1. Legen Sie als SDK mindestens iOS 12 für Ihre App fest oder erstellen Sie eine neue mobile App.

2. Umgebung für reCAPTCHA vorbereiten

3. reCAPTCHA-Schlüssel erstellen 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 Console:

     1. Rufen Sie die reCAPTCHA auf.

        Zu reCAPTCHA

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

4. Sie haben ein GitHub-Konto.

5. Weitere Informationen finden Sie in den Datenschutzdetails von Apple.

iOS-Umgebung vorbereiten

So bereiten Sie die Entwicklungsumgebung vor:

1. Laden Sie die aktuelle 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.6.0"
        ...
      
      end
      

   3. Installieren Sie die erforderlichen Abhängigkeiten,. Dazu führen Sie pod update aus.

      Hinweis: Beim Ausführen von pod clone werden die erforderlichen Abhängigkeiten nicht installiert.

   Swift-Paketmanager

   1. Wählen Sie in Xcode File > Add Packages aus und geben Sie folgende URL in das Feld Suchen oder 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 auf GitHub erstellt haben. Das Personal Access Token muss die Bereiche haben, die im Dialogfeld XCode Sign In aufgeführt sind.

      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.

      Hinweis: Fügen Sie alle Binärprogramme als statische xcframeworks hinzu.

App konfigurieren

Sie können Ihre Apps in Swift oder Objective-C schreiben.

Fügen Sie die folgenden Dateien hinzu, um Ihre App zu konfigurieren:

Swift

1. Wenn Ihre App in Swift geschrieben ist, schließen Sie den folgenden Import ein:

    import RecaptchaEnterprise
   

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 ist, gehen Sie zu Ziel > Build-Einstellungen > Swift-Standardbibliotheken immer einbetten und prüfen Sie, ob die Option auf Yes festgelegt ist.

reCAPTCHA in Ihre iOS-App einbinden

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

1. Um das SDK mit dem reCAPTCHA-Schlüssel (KEY_ID) zu instanziieren, den Sie aktualisieren Sie die App mit dem folgenden Code:

   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 nachgestellte Schließung:

      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 Mindest-Betriebssystemversion Ihrer Anwendung unter 13 liegt, verwenden Sie stattdessen einen abschließenden Abschluss:

      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. Instantiieren 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. ViewController.h aktualisieren.

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

   2. 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 einige Sekunden dauern. Um das Risiko zu minimieren Latenz haben, sollten Sie den Client so früh wie möglich initialisieren, z. B. während der onCreate()-Aufruf einer benutzerdefinierten Application-Klasse. Im reCAPTCHA SDK sollten UI-Elemente nicht blockiert werden.

2. Erstellen Sie eine Schaltfläche zum Aufrufen von reCAPTCHA und zum Auslösen von execute().

   Swift mit Storyboard

   1. Erstellen Sie im Storyboard eine Schaltfläche.
   2. Erstelle eine Aktion in ViewController, die mit der Schaltfläche verknüpft ist, die du erstellt.

   3. Rufen Sie die Methode execute() auf und übergeben Sie eine Login-Aktion, um eine reCAPTCHA-Tokens mithilfe des folgenden Code-Snippets:

      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 Mindest-Betriebssystemversion Ihrer Anwendung unter 13 liegt, verwenden Sie stattdessen einen abschließenden Abschluss:

      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 Mindest-Betriebssystemversion Ihrer Anwendung unter 13 liegt, verwenden Sie stattdessen einen abschließenden Abschluss:

      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. ContentView.swift aktualisieren

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

   Es kann einige Sekunden dauern, bis die execute API des Clients abgeschlossen ist, z. B. bei langsamen Netzwerkbedingungen oder wenn auf die Fertigstellung der Hintergrundinitialisierung gewartet wird. Die execute()-Aufrufe dürfen kein UI-Ereignis blockieren, z. B. das Drücken einer Schaltfläche.

3. Ihre Anwendung testen:

   1. reCAPTCHA verwendet AppAttest von Apple. als Teil seiner Erkennungs-Engine. Wenn Sie keinen Testschlüssel verwenden möchten mit einem festen Wert für die lokale Entwicklung:

      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. Bereinigen Sie Ihre Xcode-Build-Umgebung im Menü Product (Produkt). Klicken Sie auf Clean Build Folder (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 erstellt haben. zuvor.

   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 „method API“ zur Methode „fetchClient“ migrieren

Die Methode fetchClient gibt einen RecaptchaClient zurück. die die Initialisierung über Netzwerkfehler wiederholt. Wenn die App nicht Netzwerkzugriff nach dem Erstellen des Clients versuche, versucht der Client immer wieder, wird nach dem Erwerb eines Netzwerks erfolgreich initialisiert.

Wenn Sie execute(timeout) aufrufen und der Client noch nicht bereit ist, versucht er es zur Initialisierung vor, bevor ein Token oder ein RecaptchaErrorCode zurückgegeben werden.

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

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

Wenn die Mindestversion des Betriebssystems Ihrer Anwendung niedriger als 13 ist, verwenden Sie nachgestellte Schließung:

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

Wenn die Mindest-Betriebssystemversion Ihrer Anwendung unter 13 liegt, verwenden Sie stattdessen einen abschließenden Abschluss:

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

Zeitlimit für API-Aufrufe festlegen

Sie können einen Wert für die Zeitüberschreitung für die execute APIs angeben, indem Sie die withTimeout-Property.

Hinweis: Aus Konsistenzgründen wird standardmäßig ein Zeitlimit von 10 Sekunden verwendet.

Swift

1. Zeitlimit beim Aufrufen von execute festlegen.

     Task {
       do {
         let token = try await recaptchaClient.execute(
           withAction: RecaptchaAction.login,
           withTimeout: 10000)
         print(token)
       } catch let error as RecaptchaError {
         print(error.errorMessage)
       }
     }
   

   Wenn die Mindestversion des Betriebssystems Ihrer Anwendung unter 13 liegt, verwenden Sie stattdessen einen abschließenden Abschluss:

     recaptchaClient.execute(
       withAction: RecaptchaAction.login,
       withTimeout: 10000
     ) { token, error in
       if let token = token {
         print(token)
       } else {
         print(error)
       }
     }
   

Objective-C

1. Zeitlimit beim Aufrufen von execute festlegen.

     [recaptchaClient execute:RecaptchaAction.login
         witTimeout:10000.0
         completion:^void(NSString* _Nullable  token, NSError* _Nullable error) {
       if (!token) {
         NSLog (@"%@", (RecaptchaError *)error.errorMessage);
         return;
       }
       NSLog (@"%@", token);
     }];
   

Fehler verarbeiten

Wenn Ihre Anwendung nicht mit dem reCAPTCHA-Dienst kommunizieren kann kann dies daran liegen, dass in der API ein Fehler aufgetreten ist. Sie müssen Folgendes hinzufügen: Logik in Ihrer App implementieren, um mit solchen Fehlern umgehen zu können.

Weitere Informationen zur Risikominderung für häufige API-Fehler finden Sie unter RecaptchaErrorCode.

API-Referenz

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

Nächste Schritte

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

  Hinweis: reCAPTCHA-Antworttokens werden von Ihrem Backendserver und nicht vom Mobilgerät bewertet und kommentiert.