Google Cloud Fraud Defense in iOS-Apps einbinden

Sie können Google Cloud Fraud Defense in iOS-Apps einbinden, um Clientgerätesignale auszuwerten und mobile Nutzerinteraktionen vor automatisiertem Missbrauch zu schützen.

Aufgrund der Unterschiede bei 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 iOS-Apps nicht verfügbar. Stattdessen können Sie eine eigene gestaffelte Erzwingungsstrategie implementieren, z. B. einen MFA-Ablauf, um einen alternativen Einlösungspfad für verdächtigen Traffic bereitzustellen.

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

Warnung: Aktualisieren Sie Ihr Fraud Defense iOS Mobile SDK, um potenzielle App-Abstürze zu vermeiden. Wir haben ein technisches Problem festgestellt, das SDK-Versionen vor v18.9.0 betrifft und bei Nutzern mit iOS 27 Beta zu Abstürzen führt. Damit die Anwendung stabil bleibt und Ihre Endnutzer geschützt sind, sollten Sie die Anwendungsabhängigkeit auf die Fraud Defense iOS Mobile SDK-Version 18.9.0 oder höher aktualisieren.

Wichtig: Beachten Sie die Richtlinie zur Einstellung und Außerbetriebnahme und planen Sie ein regelmäßiges Upgrade des SDK ein.

Hinweis

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

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

2. Umgebung für Google Cloud Fraud Defense 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 Console:

     1. Rufen Sie die Seite Google Cloud Fraud Defense auf.

        Zu Google Cloud Fraud Defense

     2. Wählen Sie den Tab Keys aus.
     3. Suchen Sie in der Liste der reCAPTCHA-Schlüssel den Schlüssel, den Sie kopieren möchten, und klicken Sie dann auf .
   • Wenn Sie die ID eines vorhandenen Schlüssels mit der REST API kopieren möchten, verwenden Sie die Methode projects.keys.list.
   • Wenn Sie die ID eines vorhandenen Schlüssels mit der gcloud CLI kopieren möchten, verwenden Sie den Befehl gcloud recaptcha keys list.

4. Sie benötigen ein GitHub-Konto.

5. Datenschutzdetails von Apple lesen

iOS-Umgebung vorbereiten

So bereiten Sie die Entwicklungsumgebung vor:

1. Laden Sie die aktuelle Version von Xcode herunter, installieren Sie sie und erstellen Sie eine neue leere iOS-Anwendung mit einer Ansicht.

2. Laden Sie das SDK mit einer der folgenden Optionen 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.10.0-beta01"
        ...
      
      end
      

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

      Hinweis: Durch Ausführen von 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-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.

   React Native

   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ärdateien als statische xcframeworks hinzu.

Fraud Defense in Ihre iOS-App einbinden

So binden Sie Fraud Defense in Ihre iOS-App ein:

1. Wenn Sie das SDK mit dem von Ihnen erstellten reCAPTCHA-Schlüssel (KEY_ID) instanziieren möchten, aktualisieren Sie die Anwendung 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 kleiner als 13 ist, verwenden Sie stattdessen einen nachgestellten 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
          }
        }
      }
      

   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 kleiner 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 ein, damit Xcode die Swift-Bibliotheken finden und verknüpfen kann.

      import Foundation
      

   2. Damit der Swift-Code richtig verknüpft wird, rufen Sie Target > Build Settings > Always Embed Swift Standard Libraries auf 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 einige Sekunden dauern. Um diese Latenz zu minimieren, 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 einen Button, um reCAPTCHA aufzurufen und execute() auszulösen.

   Swift mit Storyboard

   1. Erstellen Sie im Storyboard einen Button.
   2. Erstellen Sie in ViewController eine Aktion, die mit dem von Ihnen erstellten Button verknüpft ist.

   3. Rufen Sie die Methode execute() auf und übergeben Sie eine Login-Aktion, 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 folgenden Code:

      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. 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 einen Button.
   2. Erstellen Sie in ViewController eine Aktion, die mit dem von Ihnen erstellten Button 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 mehrere Sekunden dauern, z. B. bei langsamen Netzwerkbedingungen oder wenn auf den Abschluss der Hintergrundinitialisierung gewartet wird. 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 für die lokale Entwicklung keinen Testschlüssel mit einer festen Punktzahl 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 .entitlements-Datei Ihres Projekts die App Attest-Umgebung auf production fest.

   2. Wenn Sie die Xcode-Build-Umgebung bereinigen möchten, klicken Sie im Menü Product auf Clean Build Folder.

   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. Suchen Sie im Fenster für die Debug-Ausgabe nach einem 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, versucht der Client es immer wieder und wird erfolgreich 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 RecaptchaError zurückgegeben wird.

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 kleiner 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
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 kleiner 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 dem Attribut 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. 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 nachgestellten 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
         withTimeout: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 erfolgreich mit dem reCAPTCHA-Dienst kommunizieren kann, liegt das möglicherweise daran, dass bei der API ein Fehler aufgetreten ist. Sie müssen in Ihrer App Logik hinzufügen, um solche Fehler ordnungsgemäß zu verarbeiten.

Weitere Informationen zur Behebung häufiger 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-Antworttokens werden von Ihrem Backend-Server und nicht vom Mobilgerät bewertet und annotiert.