Terminal SDK V3-Migrationsleitfaden

Erfahren Sie, wie Sie zur Version 3.0.0 des Stripe Terminal SDK migrieren.

Die iOS und Android SDKs für Stripe Terminal wurden mit einer Reihe wichtiger Änderungen an APIs und Verhalten aktualisiert, von denen einige erfordern, dass Sie Ihre Integration mit dem Stripe Terminal SDK aktualisieren. Wir nehmen regelmäßig Änderungen an wichtigen Versionsaktualisierungen vor, die sich auf die Funktionsweise oder das Verhalten Ihrer Integration auswirken können, um die Konsistenz zwischen unseren SDKs zu verbessern und Ihre Anwendungslogik und Integration zu vereinfachen. Dieser Leitfaden führt Sie durch die neuesten Änderungen und hilft Ihnen beim Upgrade Ihrer Integration.

Notiz

Erstellen Sie gerade eine neue Stripe Terminal-Integration? Auf unserer Seite zum Entwerfen einer Integration erfahren Sie, wie Sie beginnen können.

Migration zu Version 3.0.0

Hier erfahren Sie, was Sie über die Stripe Terminal iOS und Android SDKs 3.0.0 wissen müssen:

Unterstützung für die Verarbeitung von Offline-Zahlungen Beta
- Diese Funktion für den Offline-Modus befindet sich in der privaten Beta-Phase. Um Zugriff anzufordern, wenden Sie sich bitte an stripe-terminal-betas@stripe.com. Nachdem wir die Änderungen für Ihr Konto im Backend aktiviert haben, müssen Sie mithilfe des SDK die Verbindung zu Ihrem Lesegerät trennen und erneut herstellen, damit die aktualisierte Konfiguration wirksam wird.
Aktualisierungen der unterstützten Mindestversionen der Plattformen für iOS und Android
Entfernung abgeschaffter Funktionen und Eigenschaften

Wenn Ihre Anwendung zurzeit eine Terminal iOS SDK-Version vor 3.0.0. verwendet, müssen Sie einige Änderungen vornehmen, um ein Upgrade vorzunehmen und weltweit Card-Present-Zahlungen zu akzeptieren. Eine detaillierte Liste der Änderungen von Version 2.23.1 auf 3.0.0 finden Sie im SDK-Änderungsprotokoll.

Aktualisieren Sie Ihre unterstützte Mindestversion auf iOS 13 oder höher

Wir aktualisieren regelmäßig die unterstützte Mindestversion unserer SDKs, um unseren Entwicklerinnen und Entwicklern die bestmögliche Erfahrung zu bieten.

Vorhandene 2.X-Versionen des Terminal iOS SDK unterstützen weiterhin Geräte mit iOS 11 und höher.

Aktualisieren Sie Ihre Nutzung der DiscoveryConfigurationauf die spezifische DiscoveryConfiguration-Implementierung

Um die Konfiguration für verschiedene Erkennungsmethoden zu unterstützen, ist SCPDiscoveryConfiguration jetzt ein Protokoll, das von mehreren verschiedenen Typen implementiert wird. Statt einer DiscoveryMethod stehen nun einzelne Klassen zur Auswahl, um nach einem bestimmten Lesegerät zu suchen:

Konfigurationsklasse	Nutzung
SCPBluetoothScanDiscoveryConfiguration	Bluetooth-fähige Lesegeräte in der Nähe dieses iOS-Geräts
SCPBluetoothProximityDiscoveryConfiguration	Eine Teilmenge der Bluetooth-fähigen Lesegeräte in der Nähe dieses iOS-Geräts
SCPInternetDiscoveryConfiguration	Internetfähige Lesegeräte, die für dieses Konto registriert sind
SCPLocalMobileDiscoveryConfiguration	Tap to Pay unter Verwendung des NFC-Lesegeräts dieses iOS-Geräts

Erstellen Sie die für Ihre gewünschte Erkennungsmethode geeignete Erkennungskonfiguration mithilfe der angegebenen Builder-Klasse und geben Sie diese für discoverReaders an. Der Builder macht Setter für die Eigenschaften verfügbar, die von jeder Konfiguration unterstützt werden.

Aktualisieren Sie die Nutzung Ihrer discoverReader und connectReader

Das Abbrechen von discoverReaders ruft jetzt den Completion-Block mit einem Fehler mit dem Code SCPErrorCanceled auf , genau wie alle anderen annulierbaren Methoden.
discoverReaders wird jetzt erfolgreich abgeschlossen, wenn connectReader aufgerufen wird. Wenn connectReader fehlschlägt, muss Ihre Integration einen neuen Aufruf von discoverReaders durchführen, um die Suche nach Lesegeräten fortzusetzen.
discoverReaders muss nicht mehr ausgeführt werden, damit connectReader funktioniert. Sie können jetzt connectReader mit einer zuvor erkannten Lesegerät-Instanz aufrufen oder die Verbindung erneut versuchen, ohne discoverReaders neu zu starten.

Aktualisieren Sie Ihre ReconnectionDelegate-Implementierung

SCPReconnectionDelegate liefert jetzt die Instanz des Lesegeräts, mit der die Verbindung wieder hergestellt wird, statt der Terminal-Instanz. Wenn Sie diese Aufgabe zuvor implementiert haben, müssen Sie terminal in den Methodennamen durch reader ersetzen.

Aktualisieren der Nutzung von Parametern der Konfigurationsklasse, um Builders zu verwenden

Die Eingabeklassen wie SCPCollectConfiguration und SCPPaymentIntentParameters sind jetzt unveränderlich und verfügen über zugehörige Builder, um sie zu erstellen. Alle Builder verfügen über eine Build-Methode, die die Eingaben validiert und die erstellte Klasse aufbaut.

In Swift wird build() ausgelöst und sollte auf Fehler überprüft werden.
In Objective-C geben Sie den NSError ** an, um den Fehler (falls vorhanden) zu empfangen.

PaymentViewController.swift
Swift
let paymentParams = try PaymentIntentParametersBuilder(amount: 100, currency: "cad")
  .setCaptureMethod(.automatic)
  .build()

Entfernen Sie jegliche Abhängigkeit von SCPErrorBusy

SCPErrorBusy wurde entfernt. Wenn Sie in SDK 3.0.0 und höher eine Terminal-Methode aufrufen, während eine andere noch aktiv ist, werden die neuen Aufrufe jetzt in die Warteschlange gestellt. Die Befehle werden ausgeführt, nachdem alle vorherigen Befehle abgeschlossen wurden. Wenn Sie zuvor den Status verfolgt haben, um SCPErrorBusy zu verhindern, oder Ihre eigenen Befehle in die Warteschlange gestellt haben, um SCPErrorBusy zu umgehen, können Sie jetzt die Befehlswarteschlange verwenden, um Ihren Code zu vereinfachen. Wenn Ihre Anwendung sich auf SCPErrorBusy verlässt, um zu wissen, ob ein Befehl ausgeführt wird, überprüfen Sie Ihren Code, um zu sehen, ob dies zu Problemen mit dem Einreihen zu vieler Befehle in die Warteschlange führen könnte.

Überprüfen Sie die Unterstützung für Offline-Zahlungen

SCPPaymentIntent.stripeId ist für Offline-Zahlungen null. Wenn Ihre Integration nur Online-Zahlungen unterstützt, ist die stripeId immer vorhanden und es sind keine Änderungen erforderlich, abgesehen von Überprüfungen der ID. Weitere Informationen zur Offline-Verarbeitung von Zahlungen finden Sie unter Kartenzahlungen offline einziehen.

PaymentViewController.swift
Swift
Terminal.shared.createPaymentIntent(params) { intent, error in
  if let error = error {
    // Placeholder for handling exception
  }
  guard let intentId = intent.stripeId else {
    // PaymentIntent was created offline without an id. See intent.offlineDetails.
    // This is only expected when offline mode is enabled.
  }
}

Aktualisieren Sie Ihre Prozessaufrufe zur Bestätigung

SCPTerminal.processPayment wird in SCPTerminal.confirmPaymentIntent und SCPTerminal.processRefund wird in SCPTerminal.confirmRefund umbenannt. Die Parameter für diese Methoden wurden nicht geändert, aber die Fehlertypen wurden ebenfalls in SCPConfirmPaymentIntentError bzw. SCPConfirmRefundError umbenannt.

Ändern Sie Ihre readReusableCard-Nutzung in SetupIntents

SCPTerminal.readReusableCard wurde entfernt. SetupIntents sind der empfohlene Pfad zum Speichern von Karten ohne Abbuchung. SetupIntents folgen einem ähnlichen Muster wie PaymentIntents, bei denen Sie den SetupIntent im SDK erstellen, erfassen und bestätigen. Weitere Informationen finden Sie unter Karten für Online-Zahlungen speichern.