Terminal SDK-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 weltweit Card-Present-Zahlungen zu akzeptieren. Eine detaillierte Liste der Änderungen von Version 3.9.1 auf 4.0.0 finden Sie im SDK changelog.

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 vornehmen 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 Karten nach einer Zahlung.

Speichern von Karten ohne Zahlung mit SetupIntents-Integration aktualisieren

Um eine konsistente Integrationsform zwischen SetupIntents und PaymentIntents sowie persönlichen und Online-Transaktionen zu gewährleisten, haben 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 Abbuchung.

Aktualisieren Sie die Nutzung Ihrer discoverReader

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

• Wir haben die Handhabung mehrerer gleichzeitiger Lesevorgänge verbessert. Zuvor hat das mehrfache Aufrufen von discoverReaders dazu geführt, dass die Vorgänge in die Warteschlange gestellt wurden. Wenn nun ein neuer discoverReaders wird, während ein bestehender bereits im Gange ist, bricht das SDK den laufenden Vorgang ab und gibt den Fehler SCPErrorCanceledDueToIntegrationError zurück. Der neue discoverReaders-Vorgang wird sofort gestartet.

• Das Entdecken von Smart- und Tap-to-Pay-Lesern 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 Lesertypen kein langwieriger Vorgang ist.

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 Parameter ReaderDelegate aus der connectReader-Methode entfernt und stattdessen in connectionConfig verschoben, um SCPReconnectionDelegate zu ersetzen. In Übereinstimmung mit anderen Lesegerättypen erwartet die InternetConnectionConfiguration von intelligenten Lesegeräten nun auch, dass ein InternetReaderDelegate übergeben wird, das Ihre Integration über Ereignisse benachrichtigt, auch wenn ein Lesegerät die Verbindung trennt.

Vor

// 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)")
    }
}

Nach

// 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 Verbinden mit einem Lesegerät.

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

• Um die Ausfallsicherheit Ihrer Terminal-Integration mit mobilen und Tap-to-Pay-Lesegeräten zu erhöhen, haben wir die automatische Wiederverbindung standardmäßig aktiviert, wenn das Lesegerät unerwartet die Verbindung trennt.

• 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 für mobile Lesegeräte und TapToPayReaderDelegate für Tap-to-Pay-Lesegeräte, um Wiederverbindungsereignisse zu verarbeiten.

• Wenn Sie Ihre eigene Wiederverbindungslogik für Lesegeräte implementiert haben und dieses Verhalten beibehalten möchten, können Sie die automatische Wiederverbindung deaktivieren, indem Sie setAutoReconnectOnUnexpectedDisconnect auf false setzen.

Vor

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

Nach

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 Informationen und Codeausschnitte finden Sie in unserer Dokumentation zum automatischen Wiederverbindungsversuch.

Aktualisieren Sie Ihre Handhabung beim Trennen der Lesegeräte

• Um informiert zu werden, wenn ein Lesegerät die Verbindung trennt, haben wir die Rückrufe der Leserverbindung für alle Lesegerättypen konsolidiert, indem wir terminal:didReportUnexpectedReaderDisconnect: aus dem SCPTerminalDelegate entfernt haben. Verwenden Sie reader: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 die Methoden -readerDidFailReconnect: und reader:didDisconnect: aufgerufen, wenn das SDK nicht wieder mit dem Lesegerät verbunden werden kann und die Verbindung getrennt wird.

Vor

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

Nach

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 Verbindungsabbrüchen.

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 ENUM-Werte von SCPPaymentMethodType.
• 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 in 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.