Mit einem Lesegerät verbinden

Stellen Sie zunächst sicher, dass Ihr Lesegerät eingeschaltet ist und sich in unmittelbarer Nähe befindet.

Suchen Sie dann in Ihrer App mit der Methode discoverReaders mithilfe von BluetoothScanDiscoveryConfiguration nach über Bluetooth verbundenen Lesegeräten in der Nähe.

import StripeTerminal

class DiscoverReadersViewController: UIViewController, DiscoveryDelegate {

    var discoverCancelable: Cancelable?

    // ...

    // Action for a "Discover Readers" button
    func discoverReadersAction() throws {
        let config = try BluetoothScanDiscoveryConfigurationBuilder().build()
        self.discoverCancelable = Terminal.shared.discoverReaders(config, delegate: self) { error in
            if let error = error {
                print("discoverReaders failed: \(error)")
            } else {
                print("discoverReaders succeeded")
            }
        }
    }

    // ...

    // MARK: DiscoveryDelegate

    func terminal(_ terminal: Terminal, didUpdateDiscoveredReaders readers: [Reader]) {
        // In your app, display the discovered readers to the user.
        // Call `connectReader` after the user selects a reader to connect to.
    }
}

Bluetooth Proximity * BBPOS Chipper 2X BT only

Die Suchergebnisse für Bluetooth-Näherungsfilter zeigen das nächstgelegene Lesegerät an. Wenn das Lesegerät erkannt wird, blinkt es mehrfarbig, sodass Ihre Nutzer/innen das erkannte Lesegerät unter vielen anderen Lesegeräten identifizieren können. Nachdem das SDK ein Lesegerät erkannt hat, wechselt es nicht zu einem näheren Lesegerät, es sei denn, Sie schalten das erkannte Lesegerät aus.

Beachten Sie, dass das SDK bei Verwendung von Bluetooth Proximity das Lesegerät zweimal an den Callback Ihrer Anwendung zurückgibt. Beim ersten Mal erhält Ihre Anwendung ein Reader-Objekt, das nur mit der Seriennummer des Lesegeräts vorbefüllt ist. Nach einer kurzen Verzögerung erhält Ihre Anwendung dasselbe Reader-Objekt mit neuen Informationen, z. B. dem Akkustand des Lesegeräts.

Wir empfehlen, das erkannte Lesegerät auf der Nutzeroberfläche Ihrer App anzuzeigen, sodass der/die Nutzer/in die Verbindung zum Lesegerät entweder bestätigen oder abbrechen kann, wenn er/sie keine Verbindung zu diesem Lesegerät herstellen möchte.

Bluetooth-Scan

Der Bluetooth-Scan sucht nach allen in der Nähe befindlichen Lesegeräten und gibt eine Liste erkannter Lesegeräte an Ihre App zurück. Während des Erkennungsvorgangs ruft das SDK weiterhin die Methode DiscoveryDelegate.didUpdateDiscoveredReaders mit der aktuellen Liste von Lesegeräten in der Nähe auf.

Während des Erkennungsvorgangs geht der SCPConnectionStatus des Terminals in SCPConnectionStatus.SCPConnectionStatusDiscovering über, während die Erkennung ausgeführt wird.

Mit der Bluetooth-Scan-Erkennungsmethode können Sie eine Zeitüberschreitung festlegen, um die Dauer des Scans zu begrenzen. Diese können Sie zur Verwaltung der Akkulaufzeit nutzen oder um eine Fehlermeldung auszulösen, wenn kein Gerät gefunden wird.

Wir empfehlen, eine automatisch aktualisierte Liste der erkannten Lesegeräte mit Seriennummern und Bezeichnungen in Ihrer Anwendung anzuzeigen. So können Nutzer/innen leichter ihr Lesegerät identifizieren.

Um eine Verbindung zu einem erkannten Lesegerät herzustellen, rufen Sie die Methode connectReader in Ihrer App auf.

Sie müssen Ihr Lesegerät bei Einrichtung der Verbindung an einem Standort registrieren. Dazu erstellen und verwenden Sie eine BluetoothConnectionConfiguration, wobei die locationId auf die beim Verbindungsaufbau relevante Standort-ID festgelegt wird.

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

Damit Ihre App im Hintergrund ausgeführt wird und mit dem Lesegerät verbunden bleibt, müssen Sie Ihre App so konfigurieren, dass sie den gewünschten Hintergrundmodus enthält.

Umgang mit Verbindungsabbrüchen von Lesegeräten

Zwischen Ihrer App und dem Lesegerät kann es manchmal zu Verbindungsabbrüchen kommen. Dies kann zum Beispiel passieren, wenn das Lesegerät zu weit entfernt oder der Akku leer ist. Sie können eine unerwartete Unterbrechung während des Tests simulieren, indem Sie das Lesegerät ausschalten.

MobileReaderDelegate enthält die Methode reader:didDisconnect:, die Ihrer Anwendung den DisconnectReason mitteilt, um herauszufinden, warum das Lesegerät getrennt wurde.

Wenn die Verbindung zu einem Lesegerät getrennt wird, versuchen wir standardmäßig automatisch, die Verbindung wiederherzustellen. Wir empfehlen, während des gesamten Vorgangs Benachrichtigungen über den Status des Lesegeräts in Ihrer App anzuzeigen.

Gehen Sie wie folgt vor, um bei der automatischen Wiederverbindung Benachrichtigungen in Ihrer App anzuzeigen:

1. Implementieren Sie die Rückrufe für die Wiederverbindung des Lesegeräts im MobileReaderDelegate.
2. Übergeben Sie MobileReaderDelegate an Ihre BluetoothConnectionConfiguration.
3. Wenn das SDK reader:didStartReconnect:disconnectReason: an Ihre App sendet, zeigen Sie eine Meldung an, die besagt, dass die Verbindung zum Lesegerät getrennt wurde und die Verbindung erneut wiederhergestellt wird.
   • Sie können den Verbindungsversuch jederzeit mit dem Cancelable-Objekt stoppen.
4. Wenn sich das SDK wieder erfolgreich verbunden hat, nachdem readerDidSucceedReconnect: gesendet wurde, zeigen Sie eine Meldung an, die besagt, dass die Verbindung wiederhergestellt wurde und der Betrieb normal fortgesetzt werden kann.
5. Wenn sich das SDK nicht erneut mit dem Lesegerät verbinden kann und sowohl readerDidFailReconnect: als auch reader:didDisconnect: sendet, zeigen Sie eine Meldung an, die besagt, dass die Verbindung unerwartet getrennt wurde.

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

Gehen Sie wie folgt vor, um Verbindungsabbrüche selbst zu handhaben:

1. Setzen Sie autoReconnectOnUnexpectedDisconnect während der Verbindungsherstellung auf false.
2. Bearbeiten Sie den Rückruf bei Trennung son, dass nur eine Meldung in der App angezeigt wird. Diese weist die Nutzer/innen darauf hin, dass das Lesegerät unerwartet getrennt wurde, und mit der Erkennung und erneuten Verbindung des Lesegeräts begonnen werden kann.

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

Verbundenes Lesegerät neu starten

Die Lesegeräte Stripe Reader M2 und BBPOS WisePad 3 werden automatisch neugestartet, nachdem sie 24 Stunden lang in Betrieb waren. Sie können das Lesegerät jedoch mithilfe der rebootReader API zum Neustart zwingen und so diesen 24-Stunden-Rhythmus zurücksetzen. Dabei trennt sich das Lesegerät vom SDK und führt einen Neustart durch. Wenn Sie die automatische Wiederverbindung verwenden, versucht das SDK anschließend, die Verbindung mit dem Lesegerät wiederherzustellen.

Terminal.shared.rebootReader { error in
    if let error = error {
        // Placeholder for handling the error
    } else {
        // Reboot succeeded and the reader will disconnect.
        // If your app is using automatic reconnect the reconnect will begin.
    }
}

Automatische Wiederverbindung beim Anwendungsstart

Stripe Terminal verbindet sich nicht automatisch erneut mit einem Lesegerät, wenn Ihre Anwendung gestartet wird. Stattdessen können Sie einen Wiederverbindungsablauf erstellen, indem Sie Lesegerät-IDs speichern und versuchen, beim Start eine Verbindung zu einem bekannten Lesegerät herzustellen.

1. Wenn Sie erfolgreich eine Verbindung zu einem Lesegerät hergestellt haben, speichern Sie die Seriennummer an einem dauerhaften Datenspeicherort, z. B. in der UserDefaults API (iOS).

1. Wenn Ihre App gestartet wird, überprüfen Sie den dauerhaften Datenspeicherort auf eine gespeicherte Seriennummer. Wenn eines gefunden wird, rufen Sie die Methode discoverReaders auf, damit Ihre Anwendung erneut versuchen kann, dieses Lesegerät zu finden.
2. Wenn die gespeicherte Seriennummer einem der erkannten Lesegeräte entspricht, versuchen Sie, eine Verbindung zu diesem Lesegerät herzustellen, wobei Sie das übereinstimmende reader-Objekt aus dem Aufruf von discoverReaders verwenden. Wenn das zuvor verbundene Lesegerät nicht gefunden wird, brechen Sie den Erkennungsvorgang ab.

Zeigen Sie während des Erkennungs- und Verbindungsvorgangs eine Benutzeroberfläche an, um darauf hinzuweisen, dass eine automatische Wiederverbindung stattfindet.

Ihre Anwendung muss mobile Lesegeräte aktualisieren, damit Folgendes angewendet wird:

• Regionale Konfigurationen, die Sie über die Anforderungen des Kartennetzwerks und des Ausstellers auf dem Laufenden halten
• Sicherheitsupdates

Erforderliche Updates werden installiert, wenn eine Verbindung mit dem Lesegerät aufgebaut wurde. Sie können das Lesegerät erst verwenden, wenn die Aktualisierung abgeschlossen ist.

Erforderliche Aktualisierungen

Wenn für das Lesegerät sofort erforderliche Updates verfügbar sind, erhält der MobileReaderDelegate der Integration den Rückruf didStartInstallingUpdate mit einem ReaderSoftwareUpdate.

Das ReaderSoftwareUpdate enthält die notwendigen Details des Updates, einschließlich einer Schätzung der Gesamtdauer des Updates, die von durationEstimate angegeben wird.

Während des Installationsvorgangs geht der connectionStatus des Terminal in connecting über, während das Update auf dem Lesegerät installiert wird.

Ihre Anwendung muss Nutzer/innen darüber benachrichtigen, dass ein Update installiert wird, und den Fortschritt auf Ihrer Nutzeroberfläche anzeigen. Machen Sie deutlich, warum der Verbindungsaufbau länger als gewöhnlich dauern kann.

Wenn der erforderliche Aktualisierungsvorgang fehlschlägt, teilt Stripe den Fehler dem MobileReaderDelegate mit didFinishInstallingUpdate mit. Sie können sich nach einem fehlgeschlagenen erforderlichen Update nicht wieder mit dem Lesegerät verbinden, es sei denn, die folgenden Bedingungen sind erfüllt:

• Das Lesegerät führt innerhalb der letzten 30 Tage die neueste Softwareversion für den Standort aus.
• Die iOS SDK-Version ist neuer als oder gleich 3.5.0.

Wenn die Bedingungen erfüllt sind, ist der Verbindungsvorgang trotz unvollständiger Aktualisierung erfolgreich. Stripe wiederholt die erforderliche Aktualisierung, wenn Sie das nächste Mal eine Verbindung zu diesem Lesegerät herstellen, bis es erfolgreich installiert wurde.

import UIKit
import StripeTerminal

class ReaderViewController: UIViewController, MobileReaderDelegate {

    // ...

    // MARK: MobileReaderDelegate

    func reader(_ reader: Reader, didStartInstallingUpdate update: ReaderSoftwareUpdate, cancelable: Cancelable?) {
        // Show UI communicating that a required update has started installing
    }

    func reader(_ reader: Reader, didReportReaderSoftwareUpdateProgress progress: Float) {
        // Update the progress of the installation
    }

    func reader(_ reader: Reader, didFinishInstallingUpdate update: ReaderSoftwareUpdate?, error: Error?) {
        // Report success or failure of the update
    }

    // ...
}

Sie können erforderliche Aktualisierungen mithilfe des Cancelable-Objekts abbrechen, was ebenfalls zu einer fehlgeschlagenen Verbindung zum Lesegerät führt. Sie können keine inkrementellen Aktualisierungen abbrechen.

Optionale Updates

Sie können optionale Aktualisierungen bis zu dem Datum verschieben, an dem sie erforderlich werden. Das SDK benachrichtigt Sie über den MobileReaderDelegate über optionale Aktualisierungen, wenn das Lesegerät verbunden ist, aber keine Transaktion durchführt. Wenn eine optionale Aktualisierung verfügbar ist, empfängt der MobileReaderDelegate Ihrer Anwendung den Rückruf didReportAvailableUpdate mit dem ReaderSoftwareUpdate-Objekt, das die Aktualisierungsdetails enthält, darunter:

• Geschätzte Zeit für den Abschluss der Aktualisierung (durationEstimate)
• Zeitstempel, nach dem die Aktualisierung erforderlich wird (requiredAt)

Benachrichtigen Sie die Nutzer/innen in Ihrer Anwendung, wenn eine Aktualisierung verfügbar ist, und zeigen Sie eine Aufforderung an, optional mit der Aktualisierung fortzufahren.

Um mit der zuvor mit didReportAvailableUpdate gemeldeten Aktualisierung fortzufahren, rufen Sie Terminal.shared.installAvailableUpdate auf.

Das verfügbare Update wird auch als reader.availableUpdate im Reader-Objekt gespeichert.

Verhindern Sie während der Aktualisierung, dass die Nutzer/innen die Seite in Ihrer App verlassen, und weisen Sie die Nutzer/innen an, das Lesegerät in Reichweite und eingeschaltet zu lassen, bis die Aktualisierung abgeschlossen ist. Wir empfehlen, Ihren Nutzern/Nutzerinnen auch eine visuelle Anzeige des Aktualisierungsfortschritts zur Verfügung zu stellen. MobileReaderDelegate meldet den Aktualisierungsfortschritt in der Methode didReportReaderSoftwareUpdateProgress.

Wenn das requiredAt-Datum einer optionalen Aktualisierung verstrichen ist, wird die Aktualisierung erst installiert, wenn das Lesegerät verbunden wird.

import UIKit
import StripeTerminal

class ReaderViewController: UIViewController, MobileReaderDelegate {

    // ...

    // MARK: MobileReaderDelegate

    func reader(_ reader: Reader, didReportAvailableUpdate update: ReaderSoftwareUpdate) {
        // An update is available for the connected reader. Show this update in your application.
        // Install this update using `Terminal.shared.installAvailableUpdate`.
    }

}

Unter Aktualisierungen für Lesegeräte testen erfahren Sie, wie Sie sicherstellen können, dass Ihre Anwendung die verschiedenen Aktualisierungstypen für ein Lesegerät verarbeiten kann.