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 Störungen der Anwendung zu vermeiden, ist die Anzahl der im System verfügbaren Klassen auf eine sorgfältig kontrollierte Liste beschränkt.

Hinweise

  1. Legen Sie als Mindest-SDK für Ihre App iOS 12 fest oder erstellen Sie eine neue 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 Console:

      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 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 aktuelle Version von Xcode herunter und installieren Sie sie. Erstellen Sie dann eine neue, leere iOS-Einzelansichts-App.

  2. Sie haben folgende Möglichkeiten, das SDK herunterzuladen:

    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.

    Swift Package Manager

    1. Wählen Sie in Xcode File > Add Packages (Datei > Pakete hinzufügen) 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 GitHub-Anleitung 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 die zugehörigen Abhängigkeiten als xcframeworks herunterladen möchten, laden Sie den Client herunter.

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

    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 diese Latenz zu verringern, initialisieren Sie den Client so früh wie möglich, z. B. beim onCreate()-Aufruf einer benutzerdefinierten Application-Klasse. UI-Elemente sollten nicht vom reCAPTCHA SDK blockiert werden.

  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 mit einer Login-Aktion auf, 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 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. 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 mit einer Login-Aktion auf, 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 mit einer festen Bewertung 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 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 „method API“ zur Methode „fetchClient“ migrieren

Die fetchClient-Methode gibt einen RecaptchaClient zurück, der die Initialisierung bei Netzwerkfehlern noch einmal versucht. Wenn die App beim Erstellen des Clients keinen Netzwerkzugriff hat, wird der Client immer wieder neu gestartet und initialisiert, sobald ein Netzwerk gefunden wurde.

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

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

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

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

Swift

  1. Legen Sie ein Zeitlimit für den Aufruf von execute 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 Mindest-Betriebssystemversion 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. Legen Sie ein Zeitlimit für den Aufruf von execute 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 Anwendung 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 den Maßnahmen für die häufigsten 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.