Google Cloud Fraud Defense in iOS-Apps einbinden

Auf dieser Seite wird erklärt, wie Sie Google Cloud Fraud Defense in Ihre iOS-App einbinden.

Aufgrund der Unterschiede zwischen Mobilgeräten in Bezug auf Bildschirmgröße, Leistung und Benutzeroberflächen der Apps ist die visuelle reCAPTCHA-Aufgabe mit Kästchen (Ich bin kein Roboter) für mobile iOS-Apps nicht verfügbar. Stattdessen können Sie eine eigene mehrstufige Durchsetzungsstrategie implementieren, z. B. einen MFA-Ablauf, um einen alternativen Einlösungspfad für verdächtigen Traffic bereitzustellen.

Das SDK verwendet Reflektion und dynamischen Code, um die Aktualisierung und Optimierung des Erkennungssystems in bereits bereitgestellten Anwendungen oder SDKs zu ermöglichen. Um Störungen der Anwendung zu vermeiden, sind die im System verfügbaren Klassen auf eine sorgfältig kontrollierte Liste beschränkt.

Wichtig: Beachten Sie die Richtlinie zur Einstellung und Außerbetriebnahme und planen Sie, das SDK regelmäßig zu aktualisieren.

Hinweis

1. Legen Sie das Mindest-SDK Ihrer App auf iOS 15 fest oder erstellen Sie eine neue mobile App.

   **Hinweis**: reCAPTCHA unterstützt sowohl iPhones als auch iPads.

2. Bereiten Sie Ihre Umgebung für reCAPTCHA 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 Konsole, gehen Sie wie folgt vor:

     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 .
   • 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 mithilfe der gcloud CLI zu kopieren.

4. Sie benötigen ein GitHub-Konto.

5. Lesen Sie die 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.9.0"
        ...
      
      end
      

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

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

   Swift Package Manager

   1. Wählen Sie in Xcode File > Add Packages aus und geben Sie die folgende URL in das Feld Search oder Enter Package URL 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 detaillierte Anleitung zur Verwendung von reCAPTCHA über Flutter finden Sie in der Flutter-Dokumentation.

   ReactNative

   Eine detaillierte 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.

Fraud Defense in Ihre iOS-App einbinden

Führen Sie folgende Schritte in Xcode aus, um Fraud Defense 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. Aktualisieren Sie 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)).")
            }
          }
        }
      }
      

      Wenn die Mindestversion des Betriebssystems Ihrer Anwendung niedriger als 13 ist, verwenden Sie stattdessen eine nachgestellte 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 eine nachgestellte 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 hinzu, damit Xcode die Swift-Bibliotheken finden und verknüpfen kann.

      import Foundation
      

   2. Damit der Swift Code korrekt verknüpft wird, gehen Sie zu Ziel > Build-Einstellungen > Always Embed Swift Standard Libraries (Immer Swift-Standardbibliotheken einbetten) und prüfen Sie, ob die Option auf Yes festgelegt ist.

   3. Aktualisieren Sie ViewController.h.

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

   4. Aktualisieren Sie 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
      

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

2. Erstellen Sie eine Schaltfläche, um Fraud Defense 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 Methode execute() 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 eine nachgestellte 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 eine nachgestellte 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 Methode execute() 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 einige Sekunden dauern, z. B. bei langsamen Netzwerkbedingungen oder wenn sie darauf wartet, dass die Hintergrundinitialisierung abgeschlossen ist. 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 Bewertung für die lokale Entwicklung verwenden möchten, gehen Sie so vor:

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

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

   2. Klicken Sie im Menü Product (Produkt) auf Clean Build Folder (Build-Ordner bereinigen), um Ihre Xcode-Build-Umgebung zu bereinigen.

   3. Klicken Sie im Menü Product (Produkt) auf Run (Ausführen), um die Anwendung auszuführen.

   4. Klicken Sie in der geladenen Anwendung auf die zuvor erstellte Schaltfläche.

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

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

Wenn Sie execute(timeout) aufrufen und der Client noch nicht bereit ist, versucht er sich zu initialisieren, bevor er ein Token oder einen RecaptchaErrorCode zurückgibt.

Im folgenden Beispiel wird gezeigt, 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 stattdessen eine nachgestellte Closure:

// 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 Mindestversion des Betriebssystems Ihrer Anwendung niedriger als 13 ist, verwenden Sie stattdessen eine nachgestellte Closure:

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

Mit der Eigenschaft withTimeout können Sie einen Zeitlimitwert für die execute-APIs angeben.

Hinweis: Aus Konsistenzgründen wird ein Standardzeitlimit von 10 Sekunden verwendet.

Swift

1. Legen Sie beim Aufrufen von execute ein Zeitlimit fest.

     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 niedriger als 13 ist, verwenden Sie stattdessen eine nachgestellte Closure:

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

Objective-C

1. Legen Sie beim Aufrufen von execute ein Zeitlimit fest.

     [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 App nicht mit dem reCAPTCHA-Dienst kommunizieren kann, ist möglicherweise ein API-Fehler aufgetreten. Sie müssen Ihrer Anwendung eine Logik hinzufügen, um solche Fehler ordnungsgemäß zu bearbeiten.

Weitere Informationen zu 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.

  **Hinweis** :reCAPTCHA-Antworttoken werden auf Ihrem Backend-Server bewertet und mit Anmerkungen versehen, nicht auf dem Mobilgerät.