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.
Verwenden Sie das Stripe Terminal Android SDK 2.22.0 (oder höher), um USB-Verbindungen für den Stripe Reader M2 das BBPOS WisePad 3 und den BBPOS Chipper 2X BT zu unterstützen. Über USB verbundene Lesegeräte vermeiden Bluetooth-Interferenzen und Verbindungsabbrüche, indem sie eine Kabelverbindung zum Lesegerät verwenden.
Sie müssen ein USB-Kabel verwenden, das sowohl Daten als auch Aufladen unterstützt, wie das USB 2.0-Kabel, das im Lieferumfang des Stripe Reader M2 und des BBPOS WisePad 3 enthalten ist. Wenn das mit Ihrem Terminal-Lesegerät gelieferte Kabel nur zum Aufladen geeignet ist – wie das im Lieferumfang des BBPOS enthaltene Kabel Chipper 2X BT. – Verwenden Sie ein USB 2.0-Kabel eines Drittanbieters, das Daten übertragen kann.
Befolgen Sie diese Schritte, um Ihre App über ein USB-Kabel 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 entdeckenClient-seitig
Verwenden Sie die Methode discoverReaders, damit Ihre Point-of-Sale-App nach Lesegeräten in der Nähe suchen kann. Sie müssen DiscoveryConfiguration.discoveryMethod
auf USB festlegen, um über USB verbundene Geräte zu erkennen.
Achten Sie darauf, dass das Lesegerät eingeschaltet und über ein USB 2.0-Kabel mit dem Gerät verbunden ist, auf dem Ihre App ausgeführt wird. Wenn Sie dazu aufgefordert werden, gewähren Sie den Zugriff auf das über USB verbundene Lesegerät.
Wenn Sie das Lesegerät zum ersten Mal anschließen, wird eine Aufforderung des Android-Systems angezeigt, eine Verbindung zum Lesegerät herzustellen. Sie können das Kontrollkästchen „Immer geöffnet“ aktivieren, um Ihre App ohne Nachfrage zu öffnen, wenn sie mit einem Lesegerät verbunden ist.
Mit einem Lesegerät verbindenClient-seitig
Um eine Verbindung zu einem erkannten Lesegerät herzustellen, rufen Sie in Ihrer App die Methode connectUsbReader
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 Verbindung an einem Standort registrieren. Erstellen und verwenden Sie dazu eine UsbConnectionConfiguration
mit der locationId
, die beim Verbindungsaufbau auf die entsprechende Standort-ID festgelegt wird.
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.
Priorisieren Sie den Verbindungstyp
Das Terminal SDK gibt einem Verbindungstyp nicht automatisch Vorrang vor einem anderen. Wenn Sie zwischen der Erkennung von Geräten mit USB oder Bluetooth wechseln möchten, können Sie diese Funktionalität in Ihrer Point-of-Sale-App implementieren. Rufen Sie discoverReaders
auf und legen Sie die discoveryMethod
in der DiscoveryConfiguration
fest.
Um zwischen USB und Bluetooth zu wechseln, rufen Sie disconnectReader
für Ihren aktuellen Verbindungstyp auf, bevor Sie den anderen Typ initiieren. Rufen Sie für ein über Bluetooth verbundenes Lesegerät beispielsweise connectUsbReader
auf, bevor Sie disconnectReader
aufrufen.
Umgang mit Verbindungsabbrüchen von Lesegeräten
Zwischen Ihrer App und dem Lesegerät kann es manchmal zu Verbindungsabbrüchen kommen. Zum Beispiel kann das Lesegerät von Ihrer App getrennt werden, wenn das USB-Kabel, das es mit Ihrem Gerät verbindet, getrennt wird. Sie können eine unerwartete Unterbrechung während des Tests simulieren, indem Sie das Lesegerät ausschalten.
Der ReaderListener
enthält einen onDisconnect
-Rückruf, 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 UnexpectedReaderDisconnect
implementieren, um manuell zu verarbeiten, wenn ein Lesegerät die Verbindung trennt. 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 von Ihrer App getrennt werden, wenn das USB-Kabel, das es mit Ihrem Gerät verbindet, getrennt wird. Um eine unerwartete Unterbrechung während des Tests zu simulieren, schalten Sie das Lesegerät aus.
Automatisch versuchen, die Verbindung wiederherzustellen
Für diese Option muss Ihre App autoReconnectOnUnexpectedDisconnect
für die UsbConnectionConfiguration
auf true festlegen und die Callbacks aus ReconnectionListener
implementieren. Sie müssen außerdem einen autoReconnectionListener
an Ihre UsbConnectionConfiguration
ü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
onReaderReconnectStarted
. 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.
- Wenn das SDK erfolgreich erneut eine Verbindung mit dem Lesegerät herstellt, werden Sie über
onReaderReconnectSucceeded
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
onReaderReconnectFailed
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 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.
- Wenn Sie erfolgreich eine Verbindung zu einem Lesegerät hergestellt haben, speichern Sie dessen Seriennummer an einem dauerhaften Datenspeicherort wie beispielsweise der Shared Preferences API.
- Wenn Ihre App gestartet wird, suchen Sie in diesem dauerhaften Store nach einer gespeicherten 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.
Sie können während des Erkennungs- und Verbindungsvorgangs eine Benutzeroberfläche anzeigen, um darauf hinzuweisen, dass eine automatische Wiederverbindung stattfindet.
Lesegerät-Software aktualisierenClient-seitig
Sie müssen die Aktualisierung des Lesegeräts über Ihre Anwendung unterstützen. Das Lesegerät kann sich nicht selbst aktualisieren. Diese Aktualisierungen beinhalten regionale Konfigurationen, die die Einhaltung aktueller Anforderungen der Kartennetzwerke und Kartenaussteller sicherstellen, sowie mögliche Sicherheitsupdates. Bei erforderlichen Aktualisierungen wird die Installation gestartet, wenn eine Verbindung zum Lesegerät hergestellt wird, und die Installation muss abgeschlossen werden, bevor das Lesegerät verwendet werden kann.
Notiz
Für das Installieren von Updates muss der Akku des Lesegeräts zu mehr als 50 % aufgeladen sein.
Erforderliche Aktualisierungen
Wenn für das Lesegerät sofort Aktualisierungen erforderlich sind, ändert sich der Terminal connectionStatus
in ConnectionStatus.CONNECTING
, während die Änderungen gesendet werden. Der Verbindungsvorgang wird erst abgeschlossen, wenn das erforderliche Update auf dem Lesegerät installiert wurde.
Bei Aktualisierungen, die länger als 30 Sekunden dauern, empfängt der ReaderListener
Ihrer Anwendung onStartInstallingUpdate
mit einem ReaderSoftwareUpdate
-Objekt, das die Details des Updates enthält. Dies beinhaltet eine Schätzung der insgesamt für das Update benötigten Zeit, timeEstimate
.
Benachrichtigen Sie die Nutzer/innen in Ihrer App, wenn ein Update installiert wird, und zeigen Sie den Fortschritt an, damit klar wird, warum der Verbindungsvorgang länger als gewöhnlich dauert.
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 werden Ihrem ReaderListener
immer dann angekündigt, wenn das Lesegerät verbunden ist, aber keine Transaktion durchführt. Der ReaderListener
Ihrer App empfängt den Callback onReportAvailableUpdate
mit dem ReaderSoftwareUpdate
-Objekt, das die Aktualisierungsdetails enthält. Diese Aktualisierung wird auch als reader.availableUpdate
im Reader-Objekt gespeichert und beim Aufruf von Terminal.installAvailableUpdate
installiert. Das Aktualisierungsobjekt enthält eine geschätzte Aktualisierungsdauer (timeEstimate
) und das zukünftige Datum, an dem Sie das Update installieren müssen (requiredAt
).
Benachrichtigen Sie die Nutzer/innen in Ihrer App über das verfügbare Update und zeigen Sie eine Aufforderung an, optional mit dem Update fortzufahren. Rufen Sie zum Fortfahren installAvailableUpdate
auf, um das Update in onReportAvailableUpdate
zu installieren.
Verhindern Sie, dass Nutzer/innen die Seite in Ihrer App verlassen, während das Update installiert wird, und weisen Sie sie an, das Lesegerät angeschlossen und eingeschaltet zu lassen, bis das Update abgeschlossen ist. Wir empfehlen, Ihren Nutzer/innen eine visuelle Anzeige des Fortschritts der Aktualisierung zur Verfügung zu stellen. Sie können die Methode onReportReaderSoftwareUpdateProgress
in Ihrem ReaderListener
verwenden.
Wenn das requiredAt
-Datum verstrichen ist, wird das optionale Update erst installiert, wenn Sie das Lesegerät trennen und erneut verbinden.
Sie können optionale Updates auch zurückstellen, diese werden jedoch erforderlich, wenn Sie sie nicht bis zu einem bestimmten Datum installieren.
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.