reCAPTCHA Enterprise in iOS-Apps einbinden

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

Aufgrund der Unterschiede bei Mobilgeräten in Bezug auf Bildschirmgröße, Leistung und Benutzeroberfläche der Apps ist die reCAPTCHA-Abfrage für das visuelle Kästchen (Ich bin kein Roboter) für mobile iOS-Apps nicht verfügbar. Sie können stattdessen Ihre eigene gestaffelte Erzwingungsstrategie implementieren, z. B. einen MFA-Ablauf, um einen alternativen Einlösungspfad für verdächtigen Traffic bereitzustellen.

Hinweis: Das SDK nutzt Reflexion und dynamischen Code, um das Erkennungssystem in bereits bereitgestellten Anwendungen oder SDKs zu aktualisieren und zu optimieren. Die im System verfügbaren Klassen sind auf eine sorgfältig kontrollierte Liste beschränkt, um Störungen der Anwendung zu vermeiden.

Hinweise

1. Legen Sie als Mindest-SDK Ihrer App iOS 11 fest oder erstellen Sie eine neue mobile App.

2. Bereiten Sie Ihre Umgebung für reCAPTCHA Enterprise vor.

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

     1. Rufen Sie die Seite reCAPTCHA Enterprise auf.

        Zur Seite „reCAPTCHA Enterprise“

     2. Bewegen Sie den Mauszeiger in der Liste der reCAPTCHA-Schlüssel auf den Schlüssel, den Sie kopieren möchten, und klicken Sie dann auf .
   • Wenn Sie die ID eines vorhandenen Schlüssels mithilfe der REST API kopieren möchten, verwenden Sie die Methode projects.keys.list.
   • Wenn Sie die ID eines vorhandenen Schlüssels mithilfe der gcloud CLI kopieren möchten, verwenden Sie den Befehl gcloud reCAPTCHA keys list.

4. Sie haben ein GitHub-Konto.

5. Datenschutzinformationen von Apple

iOS-Umgebung vorbereiten

So bereiten Sie die Entwicklungsumgebung vor:

1. Laden Sie die neueste Version von Xcode herunter, installieren Sie sie und erstellen Sie eine neue leere iOS-Single View-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.5.0"
        ...
      
      end
      

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

      Hinweis: Durch das 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 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 Informationen ein:

      • GitHub-Nutzername.
      • Ein persönliches Zugriffstoken, das Sie mithilfe der Anleitung von GitHub erstellt haben. Für das Personal Access Token (Persönliche Zugriffstoken) müssen die Bereiche vorhanden sein, die im Dialogfeld XCode Sign In (XCode-Anmeldung) aufgeführt sind.

      Xcode installiert das SDK und die erforderlichen Abhängigkeiten.

   Flutter

   Eine ausführliche Anleitung zur Verwendung von reCAPTCHA Enterprise mit Flutter finden Sie in der Dokumentation zu Flutter.

   ReactNative

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

   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, führen 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. Um sicherzustellen, dass der Swift-Code korrekt 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 Enterprise in Ihre iOS-App einbinden

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

Hinweis: Die Latenz des reCAPTCHA SDK kann hoch sein. Daher wird empfohlen, Recaptcha.getClient(siteKey:) und execute() so früh wie möglich aufzurufen, z. B. wenn die Anwendung geladen wird. UI-Elemente sollten im reCAPTCHA SDK nicht blockiert werden.

1. Um das SDK mit dem von Ihnen erstellten reCAPTCHA-Schlüssel (KEY_ID) zu instanziieren, 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 {
              let client = try await Recaptcha.getClient(withSiteKey: "KEY_ID")
              self.recaptchaClient = client
            } catch let error as RecaptchaError {
               print("RecaptchaClient creation error: \(String(describing: error.errorMessage)).")
            }
          }
        }
      }
      

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

      import RecaptchaEnterprise
      
      class ViewController: UIViewController {
        var recaptchaClient: RecaptchaClient?
      
        override func viewDidLoad() {
          super.viewDidLoad()
          Recaptcha.getClient(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 {
              let client = try await Recaptcha.getClient(withSiteKey: "KEY_ID")
              self.recaptchaClient = client
            } catch let error as RecaptchaError {
               print("RecaptchaClient creation error: \(String(describing: error.errorMessage)).")
            }
          }
        }
      }
      

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

      import RecaptchaEnterprise
      
      class ViewController: UIViewController {
        var recaptchaClient: RecaptchaClient?
      
        override func viewDidLoad() {
          super.viewDidLoad()
          Recaptcha.getClient(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. ViewController.h aktualisieren.

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

   2. ViewController.m aktualisieren.

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

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

   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 Methode execute() auf und übergeben Sie die Aktion Login, um ein reCAPTCHA-Token zurückzugeben. Verwenden Sie dazu das folgende Code-Snippet:

      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 kleiner als 13 ist, verwenden Sie stattdessen einen nachgestellten 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 Code zum Ausführen:

      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 kleiner als 13 ist, verwenden Sie stattdessen einen nachgestellten 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 Methode execute() auf und übergeben Sie die Aktion Login, um ein reCAPTCHA-Token zurückzugeben. Verwenden Sie dazu das folgende Code-Snippet:

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

3. Ihre Anwendung testen:

   1. reCAPTCHA Enterprise verwendet AppAttest von Apple als Teil seiner Erkennungs-Engine. Wenn Sie keinen Testschlüssel mit einem festen Wert 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. Klicken Sie zum Bereinigen der Xcode-Build-Umgebung 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.

Zeitlimit für API-Aufrufe festlegen

Mit dem Attribut withTimeout der einzelnen APIs können Sie einen Zeitüberschreitungswert für die APIs getClient und execute angeben.

Hinweis: Aus Konsistenzgründen wird sowohl für die getClient- als auch für die execute-APIs ein Standardzeitlimit von 10 Sekunden verwendet.

Swift

1. Zeitlimit beim Aufrufen von getClient festlegen.

       Task {
         do {
           self.recaptchaClient = try await Recaptcha.getClient(
             withSiteKey: "KEY_ID",
             withTimeout: 15000
           )
         } catch let error as RecaptchaError {
             print("RecaptchaClient creation error: \(String(describing: error.errorMessage)).")
         }
       }
   

   Wenn die Mindestversion des Betriebssystems Ihrer Anwendung kleiner als 13 ist, verwenden Sie stattdessen einen abschließenden Closure:

     Recaptcha.getClient(
       withSiteKey: "KEY_ID",
       withTimeout: 15000
     ) { client, error in
       guard let client = client else {
           print("RecaptchaClient creation error: \(error).")
         return
       }
       self.recaptchaClient = client
     }
   

2. 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 kleiner als 13 ist, verwenden Sie stattdessen einen abschließenden Closure:

     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 getClient festlegen.

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

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

API-Referenz

Eine vollständige Referenz der reCAPTCHA API for iOS finden Sie unter RecaptchaEnterprise.

Nächste Schritte

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

  Hinweis: reCAPTCHA-Antworttokens werden von Ihrem Backend-Server aus bewertet und annotiert, nicht vom Mobilgerät aus.