Mit einem Lesegerät verbinden
Notiz
Wenn Sie sich noch nicht für ein Lesegerät entschieden haben, vergleichen Sie die verfügbaren Terminal-Lesegeräte und wählen Sie eines aus, das Ihren Bedürfnissen am besten entspricht.
Über Bluetooth verbundene Lesegeräte sind Bluetooth LE-Geräte. Sie erfassen Zahlungsdetails, sind aber für die Kommunikation mit Stripe auf ein gekoppeltes Mobilgerät angewiesen.
Befolgen Sie diese Schritte, um Ihre App über Bluetooth mit einem Terminal-Lesegerät zu verbinden:
Vorsicht
Koppeln Sie das Lesegerät nicht über die Einstellungen des mobilen Geräts. Durch Koppeln des Lesegeräts über die Einstellungen des mobilen Geräts wird die Verbindung des Lesegeräts zu Ihrer App verhindert.
Lesegeräte suchenClientseitig
Schalten Sie zuerst das Lesegerät ein. Suchen Sie dann in Ihrer App mit der Methode discoverReaders nach mit Bluetooth verbundenen Lesegeräten in der Nähe.
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 gefundene Lesegerät auf der Nutzeroberfläche Ihrer App anzuzeigen und dem/der Nutzer/in die Möglichkeit zu geben, die Verbindung mit dem Lesegerät zu bestätigen oder abzubrechen, wenn er/sie keine Verbindung mit dem 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.
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.
Mit einem Lesegerät verbindenClientseitig
Um eine Verbindung zu einem erkannten Lesegerät herzustellen, rufen Sie in Ihrer App die Methode connectBluetoothReader
auf. Sobald das SDK mit dem Lesegerät verbunden ist, leuchtet die Statusanzeige des Lesegeräts durchgehend blau.
Sie müssen Ihr Lesegerät bei Einrichtung der Verbindung bei einem Standort registrieren. Dazu erstellen und verwenden Sie eine BluetoothConnectionConfiguration
, wobei die locationId
auf die beim Verbindungsaufbau relevante Standort-ID gesetzt wird.
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.
Programmieren Sie Ihre App nicht so, dass sie disconnectReader
aufruft, um Strom zu sparen. Das Lesegerät verwaltet den Strom effizient über seinen Standby-Modus.
Umgang mit Verbindungsabbrüchen von Lesegeräten
Zwischen Ihrer App und dem Lesegerät kann es manchmal zu Verbindungsabbrüchen kommen. Beispielsweise kann das Lesegerät von Ihrer App getrennt werden, wenn es sich außerhalb der Reichweite befindet oder der Akku leer ist. Sie können eine unerwartete Unterbrechung während des Tests simulieren, indem Sie das Lesegerät ausschalten.
Das BluetoothReaderDelegate
enthält den Parameter reader:didDisconnect:
, der Ihrer Anwendung den DisconnectReason
mitteilt, um herauszufinden, warum das Lesegerät getrennt wurde.
Es gibt zwei Möglichkeiten, mit Verbindungsabbrüchen umzugehen:
Behandeln Sie die Trennung sofort
Für diese Option muss Ihre App den Rückruf didReportUnexpectedReaderDisconnect
implementieren, um manuell zu handhaben, wenn die Verbindung zu einem Lesegerät getrennt wird. Dies ist das Standardverhalten des SDK.
Zeigen Sie in Ihrer Implementierung dieses Callbacks eine Nutzeroberfläche an, um die Nutzer/innen darüber zu informieren, dass die Verbindung zum Lesegerät getrennt wurde.
Das Lesegerät kann die Verbindung zu Ihrer App verlieren, wenn es sich außerhalb der Reichweite befindet oder der Akku leer ist. Schalten Sie das Lesegerät aus, um eine unerwartete Unterbrechung während des Tests zu simulieren.
Automatisch versuchen, die Verbindung wiederherzustellen
Für diese Option muss Ihre App autoReconnectOnUnexpectedDisconnect
in der BluetoothConnectionConfiguration
auf true festlegen und die Callbacks aus ReconnectionDelegate
implementieren. Sie müssen außerdem ein autoReconnectionDelegate
an Ihre BluetoothConnectionConfiguration
übergeben.
Wenn Sie automatisch versuchen, die Verbindung wiederherzustellen, geschieht Folgendes:
- Wenn die Verbindung getrennt wird, versucht das SDK automatisch, die Verbindung wiederherzustellen, und benachrichtigt Sie über
didStartReaderReconnect
. Stellen Sie sicher, dass Ihre App meldet, dass die Verbindung unterbrochen wurde und eine erneute Verbindung durchgeführt wird.- Sie können den Verbindungsversuch jederzeit mit dem
Cancelable
-Objekt stoppen.
- Sie können den Verbindungsversuch jederzeit mit dem
- Wenn sich das SDK erfolgreich mit dem Lesegerät verbindet, werden Sie über
didSucceedReaderReconnect
benachrichtigt. Stellen Sie sicher, dass Ihre App meldet, dass die Verbindung wiederhergestellt wurde, und dass der normale Betrieb fortgesetzt wird. - Wenn sich das SDK nicht erneut mit dem Lesegerät verbinden kann, werden Sie über
didFailReaderReconnect
benachrichtigt. Stellen Sie sicher, dass Ihre App eine unerwartete Trennung der Verbindung meldet.
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.
Automatische Wiederverbindung beim Anwendungsstart
Stripe Terminal stellt nicht automatisch eine Verbindung zu einem Lesegerät wieder her, 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.
- 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).
- 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. - 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.
Lesegerätesoftware aktualisierenClientseitig
Sie müssen die Aktualisierung des Bluetooth-Lesegeräts über Ihre Anwendung unterstützen. Das Lesegerät kann sich nicht selbst aktualisieren. Diese Updates umfassen regionale Konfigurationen, die Sie über die Anforderungen des Kartennetzwerks und der Kartenaussteller sowie über potenzielle Sicherheitsupdates auf dem Laufenden halten. Erforderliche Updates werden bei Verbindung mit dem Lesegerät installiert und müssen abgeschlossen sein, bevor das Lesegerät verwendet werden kann.
Notiz
Um Updates installieren zu können, muss die Akkulaufzeit des Lesegeräts mindestens 50 % betragen.
Erforderliche Aktualisierungen
Wenn für das Lesegerät sofort erforderliche Updates verfügbar sind, erhält der BluetoothReaderDelegate
der Integration den Rückruf didStartInstallingUpdate
mit einem ReaderSoftwareUpdate
. Das ReaderSoftwareUpdate
enthält die erforderlichen Details des Updates, einschließlich einer Schätzung der Gesamtupdate-Dauer, die von estimatedUpdateTime
angegeben wird. Während des Installationsvorgangs geht der connectionStatus
des Terminal auf 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 Verbindungsvorgang länger als gewöhnlich dauert.
Wenn der erforderliche Aktualisierungsprozess fehlschlägt, teilt Stripe den Fehler dem BluetoothReaderDelegate
mit. Der Verbindungsversuch schlägt mit demselben Fehler fehl, 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.
Sie können erforderliche Aktualisierungen mithilfe des Cancelable
-Objekts abbrechen. Dadurch schlägt die Verbindung zum Lesegerät jedoch fehl. Für inkrementelle Aktualisierungen steht kein Cancelable
-Objekt zur Verfügung, da diese Aktualisierungen nicht abgebrochen werden können.
Optionale Updates
Optionale Aktualisierungen können verzögert werden, werden jedoch erforderlich, wenn sie bis zu einem bestimmten Datum nicht installiert wurden. Optionale Aktualisierungen werden Ihrem BluetoothReaderDelegate
jederzeit gemeldet, wenn eine Verbindung hergestellt, aber keine Transaktion durchführt wird. Wenn eine optionale Aktualisierung verfügbar ist, empfängt das BluetoothReaderDelegate
Ihrer Anwendung den didReportAvailableUpdate
-Rückruf mit dem ReaderSoftwareUpdate
-Objekt, das die Aktualisierungsdetails enthält. Diese Aktualisierung wird auch im Reader-Objekt als reader.availableUpdate
gespeichert und ist die Aktualisierung, die beim Aufruf von Terminal.installAvailableUpdate
installiert wird. Das Update-Objekt beinhaltet eine geschätzte Dauer der Aktualisierung (estimatedUpdateTime
) und das Datum in der Zukunft, bis zu dem die Aktualisierung installiert werden muss (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 Aktualisierung fortzufahren, rufen Sie installAvailableUpdate
auf. Dadurch wird die zuvor über didReportAvailableUpdate
gemeldete Aktualisierung installiert.
Sorgen Sie während der Aktualisierung dafür, dass Ihre Nutzer/innen die Seite in Ihrer App nicht verlassen. Weisen Sie sie an, das Lesegerät in Verbindungsreichweite und eingeschaltet zu lassen, bis die Aktualisierung abgeschlossen ist. Sie sollten Ihren Nutzer/innen außerdem eine visuelle Anzeige des Aktualisierungsfortschritts anbieten. Das BluetoothReaderDelegate
meldet den Fortschritt der Aktualisierung über die Methode didReportReaderSoftwareUpdateProgress
.
Wenn das requiredAt
-Datum einer optionalen Aktualisierung verstrichen ist, wird die Aktualisierung erst installiert, wenn das Lesegerät getrennt und erneut verbunden wird.
Unter Aktualisierungen für Bluetooth-Lesegeräte testen erfahren Sie, wie Sie sicherstellen können, dass Ihre Anwendung die verschiedenen Aktualisierungstypen für ein Lesegerät verarbeiten kann.
Nächste Schritte
Sie haben Ihre Anwendung mit dem Lesegerät verbunden. Ziehen Sie als Nächstes Ihre Stripe Terminal-Zahlung ein.
Der Name und das Logo von BBPOS und Chipper™ sind Marken oder eingetragene Marken von BBPOS Limited in den Vereinigten Staaten und/oder anderen Ländern. Der Name und das Logo von Verifone® sind entweder Marken oder eingetragene Marken von Verifone in den Vereinigten Staaten und/oder anderen Ländern. Die Verwendung der Marken stellt keine Billigung durch BBPOS oder Verifone dar.