Terminal-SDK V4-Migrationsleitfaden

Wenn Ihre Anwendung derzeit eine Terminal iOS-SDK-Version vor 4.0.0 verwendet, müssen Sie einige Änderungen vornehmen, um ein Upgrade vorzunehmen und weltweite Zahlungen mit vorliegender Karte zu akzeptieren. Eine detaillierte Liste der Änderungen von Version 3.9.1 auf 4.0.0 finden Sie im SDK-Änderungsprotokoll.

Aktualisieren Sie Ihre unterstützte Mindestversion auf iOS 14 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 3.X-Versionen des Terminal-iOS-SDK unterstützen weiterhin Geräte mit iOS 13 und höher.

Speichern von Karten nach der Integration von PaymentIntents aktualisieren

Wenn Sie eine Zahlungsmethode nach einem erfolgreichen persönlichen PaymentIntent speichern, müssen Sie die folgenden Aktualisierungen an Ihrer Integration vornehmen:

• Übergeben Sie beim Erstellen von Terminal-PaymentIntents den Parameter setup_future_usage, der Stripe darüber informiert, dass Sie zukünftige Zahlungen mit derselben Karte durchführen möchten.

• Sie müssen auch allow_redisplay als always oder limited in SCPCollectConfiguration übergeben. Übergeben Sie always, wenn Sie möchten, dass die gespeicherte Karte des Kunden/der Kundin in allen zukünftigen Bezahlvorgängen angezeigt wird, und limited, wenn sie nur im Kontext der anfänglich festgelegten Nutzung verwendet werden kann, zum Beispiel bei einem Abonnement.

  Erfahren Sie mehr über das Speichern von Zahlungsdaten nach einer Zahlung.

Speichern von Karten ohne Zahlung mit der SetupIntents-Integration aktualisieren

Um ein konsistentes Integrationsmuster zwischen SetupIntents und PaymentIntents sowie Vor-Ort- und Online-Transaktionen zu gewährleisten, haben wir in der collectSetupIntentPaymentMethod von SCPTerminal den Parameter customerConsentCollected entfernt, der zuvor für alle SetupIntent-Transaktionen erforderlich war, und durch den Parameter allowRedisplay ersetzt.

Erfahren Sie mehr über das direkte Speichern ohne Zahlung.

Aktualisieren Sie die Nutzung Ihrer discoverReaders

• Wir haben den neuen Enumerations-Wert discovering zum SCPConnectionStatus hinzugefügt, um darzustellen, wann Reader Discovery ausgeführt wird. Stellen Sie sicher, dass Ihre Integration diesen neuen Zustand verarbeiten und Ihren Kundinnen und Kunden relevante Informationen bereitstellen kann.

• Wir haben die Verarbeitung mehrerer gleichzeitiger Lesegerät-Erkennungsvorgänge verbessert. Bisher wurden die Vorgänge durch mehrfachen Aufruf von discoverReaders in die Warteschlange gestellt. Wenn nun ein neuer discoverReaders aufgerufen wird, während ein bestehender bereits ausgeführt wird, bricht das SDK den laufenden Vorgang ab und gibt einen SCPErrorCanceledDueToIntegrationError-Fehler zurück. Der neue DiscoverReaders-Vorgang beginnt dann sofort.

• Das Entdecken von Smart- und Tap-to-Pay-Lesegeräten ruft jetzt den Abschlussblock discoverReaders auf, wenn der Vorgang endet. Diese Änderung spiegelt die Tatsache wider, dass die Entdeckung von Lesegeräten für diese Lesegerätetypen kein langwieriger Vorgang ist.

• Wir haben einen Fehler behoben, der einen starken Verweis auf den SCPDiscoveryDelegate im SDK enthielt. Stellen Sie sicher, dass Ihre Anwendung einen starken Verweis auf Ihren Delegierten enthält, um die Erkennungsereignisse zu empfangen.

Aktualisieren Sie die Nutzung Ihrer Lesegerätverbindung

• Um ein konsistentes Integrationsmuster für die Erkennung und Verbindung von Lesegeräten zu gewährleisten, haben wir alle vorherigen Verbindungsmethoden für Lesegeräte (connectBluetoothReader, connectInternetReader, connectLocalMobileReader) in connectReader konsolidiert. Der genaue Verbindungstyp wird weiterhin durch die übergebene Verbindungskonfiguration bestimmt.

• Für mobile Lesegeräte und Tap-to-Pay-Geräte wurde der ParameterReaderDelegate aus der Methode connectReader entfernt und stattdessen in connectionConfig verschoben, um SCPReconnectionDelegate zu ersetzen. In Übereinstimmung mit anderen Lesegerättypen erwartet die InternetConnectionConfiguration nun auch einen InternetReaderDelegate, der übergeben wird, der Ihre Integration über Ereignisse benachrichtigt, auch wenn ein Lesegerät die Verbindung trennt.

Vorher

// Call `connectBluetoothReader` with the selected reader and a connection config
// to register to a location as set by your app.
let connectionConfig: BluetoothConnectionConfiguration
do {
    connectionConfig = try BluetoothConnectionConfigurationBuilder(locationId: 
"{{LOCATION_ID}}").build()
} catch {
    // Handle the error building the connection configuration
    return
}
Terminal.shared.connectBluetoothReader(selectedReader, delegate: readerDelegate, connectionConfig: connectionConfig) { reader, error in
    if let reader = reader {
        print("Successfully connected to reader: \(reader)")
    } else if let error = error {
        print("connectBluetoothReader failed: \(error)")
    }
}

Nachher

// Call `connectReader` with the selected reader and a connection config
// to register to a location as set by your app.
let connectionConfig: BluetoothConnectionConfiguration
do {
    connectionConfig = try BluetoothConnectionConfigurationBuilder(delegate: yourMobileReaderDelegate, locationId: 
"{{LOCATION_ID}}")
    .build()
} catch {
    // Handle the error building the connection configuration
    return
}
Terminal.shared.connectReader(selectedReader, connectionConfig: connectionConfig) { reader, error in
    if let reader = reader {
        print("Successfully connected to reader: \(reader)")
    } else if let error = error {
        print("connectReader failed: \(error)")
    }
}

Weitere Informationen finden Sie in unserer Dokumentation zum Anschließen an ein Lesegerät.

Die automatische Wiederverbindung ist jetzt standardmäßig für mobile und Tap-to-Pay-Lesegeräte aktiviert

• Um die Widerstandsfähigkeit Ihrer Terminal-Integration mit mobilen und Tap-to-Pay-Lesegeräten zu erhöhen, haben wir standardmäßig die automatische Wiederverbindung aktiviert, wenn ein Lesegerät unerwartet getrennt wird.

• Wir empfehlen, Benachrichtigungen in Ihrer App anzuzeigen, um die Nutzer/innen während des gesamten Wiederverbindungsvorgangs über den Lesegerätstatus zu informieren. Für die Handhabung von Wiederverbindungsmethoden für Lesegeräte haben wir SCPReconnectionDelegate entfernt. Ihre Zuständigkeiten wurden in die jeweiligen ReaderDelegates integriert. Verwenden Sie MobileReaderDelegate for mobile Lesegeräte und TapToPayReaderDelegate für Tap-to-Pay-Lesegeräte, um Wiederverbindungsereignisse zu verarbeiten.

• Wenn Sie Ihre eigene Logik zur Wiederverbindung des Lesegeräts implementiert haben und dieses Verhalten beibehalten möchten, können Sie die automatische Wiederverbindung deaktivieren, indem Sie setAutoReconnectOnUnexpectedDisconnect auf false setzen.

Vorher

import StripeTerminal

extension ReaderViewController: ReconnectionDelegate {
    // MARK: ReconnectionDelegate
    func terminal(_ terminal: Terminal, didStartReaderReconnect cancelable: Cancelable) {
        // 1. Notified at the start of a reconnection attempt
        // Use cancelable to stop reconnection at any time
    }

    func terminalDidSucceedReaderReconnect(_ terminal: Terminal) {
        // 2. Notified when reader reconnection succeeds
        // App is now connected
    }
    func terminalDidFailReaderReconnect(_ terminal: Terminal) {
        // 3. Notified when reader reconnection fails
        // App is now disconnected
    }
}

Nachher

import StripeTerminal

extension ReaderViewController: MobileReaderDelegate {
    // MARK: MobileReaderDelegate

    func reader(_ reader: Reader, didStartReconnect cancelable: Cancelable, disconnectReason: DisconnectReason) {
        // 1. Notified at the start of a reconnection attempt
        // Use cancelable to stop reconnection at any time
    }

    func readerDidSucceedReconnect(_ reader: Reader) {
        // 2. Notified when reader reconnection succeeds
        // App is now connected
    }
    func readerDidFailReconnect(_ reader: Reader) {
        // 3. Notified when reader reconnection fails
        // App is now disconnected
    }
}

Weitere Details und Codeausschnitte finden Sie unter Automatischer Verbindungsversuch.

Aktualisieren Ihrer Handhabung der Verbindungstrennung des Lesegeräts

• Um informiert zu werden, wenn ein Lesegerät die Verbindung trennt, haben wir die Rückrufe zur getrennten Lesegerät-Verbindung für alle Lesegerätetypen konsolidiert, indem wir terminal:didReportUnexpectedReaderDisconnect:`` aus dem SCPTerminalDelegateentfernt haben. Verwenden Siereader:didDisconnect:` als Teil von ReaderDelegates, um benachrichtigt zu werden, wenn ein Lesegerät getrennt wird. Bei mobilen Lesegeräten kann der SCPDisconnectReason helfen, den Grund für die Trennung zu identifizieren.

Wenn die automatische Wiederverbindung aktiviert ist, werden sowohl die Methoden -readerDidFailReconnect: als auch reader:didDisconnect: aufgerufen, wenn das SDK keine erneute Verbindung zum Lesegerät herstellen kann und die Verbindung getrennt wird.

Vorher

import StripeTerminal

class ReaderViewController: UIViewController, TerminalDelegate {
    override func viewDidLoad() {
        super.viewDidLoad()
        Terminal.shared.delegate = self
    }

    // ...
    // MARK: TerminalDelegate
    func terminal(_ terminal: Terminal, didReportUnexpectedReaderDisconnect reader: Reader) {
        // Consider displaying a UI to notify the user and start rediscovering readers
    }
}

Nachher

import StripeTerminal

class ReaderViewController: UIViewController, MobileReaderDelegate {
    override func viewDidLoad() {
        super.viewDidLoad()
        // Set the reader delegate when connecting to a reader
    }

    // ...



    func reader(_ reader: Reader, didDisconnect reason: DisconnectReason) {
        // Consider displaying a UI to notify the user and start rediscovering readers
    }
}

Weitere Informationen finden Sie in unserer Dokumentation zum manuellen Umgang mit Verbindungstrennungen.

Aktualisieren Sie Ihre Integration für die Zahlungsannahme

• Sie können confirmPaymentIntent jetzt mit dem zurückgegebenen Objekt Cancelable stornieren. Dies ist nützlich für QR-Code-Zahlungen, die einen asynchronen Bestätigungsprozess haben. Auch confirmSetupIntent und confirmRefund können jetzt storniert werden.
• Wir haben die Typensicherheit und Konsistenz zwischen den mobilen SDKs verbessert, indem wir die Art und Weise aktualisiert haben, wie paymentMethodTypes in SCPPaymentIntentParameters und SCPSetupIntentParameters. angegeben werden. Zuvor wurde dieser Parameter als ein Array von Zeichenfolgen dargestellt (zum Beispiel [„card_present“]). Es verwendet jetzt Enumerationswerte vonSCPPaymentMethodType.
• Um den Stornierungsablauf für PaymentIntents und SetupIntents zu verbessern, werden mit dem Aufruf von Terminal::cancelPaymentIntent oder Terminal::cancelSetupIntent nun auch alle laufenden Zahlungsvorgänge abgebrochen. Sie müssen Zahlungsvorgänge wie .collectPaymentMethod nicht mehr separat stornieren, bevor Sie den PaymentIntent stornieren.
• SCPSetupIntent.stripeId kann nun auf Null gesetzt werden, um mit SCPPaymentIntent.stripeId konsistent zu sein. Obwohl der Wert stripeId weiterhin existiert, stellen Sie sicher, dass Ihr Code den Fall, in dem SCPSetupIntent.stripeId möglicherweise null ist, sicher verarbeitet, um Compiler-Fehler zu vermeiden.

Nutzung für Umbenennung und Deprecation aktualisieren

• BluetoothReaderDelegate wurde in MobileReaderDelegate umbenannt.
• In SCPReaderSoftwareUpdate, haben wir SCPUpdateTimeEstimate in SCPUpdateDurationEstimate und estimatedUpdateTime in durationEstimate umbenannt, um ihre Absicht besser darzustellen.
• In SCPOfflineDetails, das Zahlungsdetails darstellt, die verfügbar sind, wenn eine Zahlung offline erstellt oder bestätigt wird, haben wir die Zeit, zu der die Offline-Zahlung stattgefunden hat, von collectedAt auf storedAt umbenannt, wobei wir uns an den Namenskonventionen im Terminal-Android-SDK orientieren.
• Wir haben in allen SDK-Funktionsnamen und Fehlercodes „local mobile“ und „apple built in“ in „Tap to Pay“ umbenannt.