Se connecter à un lecteur
Note
Si vous n’avez pas encore choisi de lecteur, comparez les lecteurs Terminal et sélectionnez celui qui répond au mieux à vos exigences.
Utilisez le SDK Android Stripe Terminal 2.22.0 (ou une version ultérieure) pour prendre en charge les connexions USB pour le lecteur M2 de Stripe, BBPOS WisePad 3 et les lecteurs BBPOS Chipper 2X BT. Une connexion filaire par USB permet d’éviter les interférences Bluetooth et les problèmes de déconnexion des lecteurs.
Vous devez utiliser un câble USB qui prend en charge à la fois le transfert de données et la charge, comme le câble USB 2.0 qui est inclus avec le lecteur Stripe M2 et le BBPOS WisePad 3. Si le câble fourni avec votre lecteur de terminal ne permet que la charge, comme celui fourni avec le BBPOS Chipper 2X BT, utilisez un câble USB 2.0 tiers qui peut transférer des données.
Suivez ces étapes pour connecter votre application à un lecteur de terminal à l’aide du câble USB :
Mise en garde
N’utilisez pas des paramètres d’appareil mobile pour associer votre lecteur. L’association du lecteur via les paramètres de l’appareil empêche sa connexion à votre application.
Détecter les lecteursCôté client
Utilisez la méthode discoverReaders pour permettre à votre application de point de vente de rechercher des lecteurs à proximité. Vous devez définir DiscoveryConfiguration.discoveryMethod
sur USB pour détecter les appareils connectés en USB.
Assurez-vous que le lecteur est allumé et connecté avec un câble USB 2.0 à l’appareil qui exécute votre application. Lorsque vous y êtes invité, accordez la permission d’accéder au lecteur connecté en USB.
Si vous branchez le lecteur pour la première fois, une invite du système Android s’affiche pour vous demander de vous connecter au lecteur. Vous pouvez cocher la case « Toujours ouvert » pour ouvrir votre application sans demande lorsqu’elle est connectée à un lecteur.
Se connecter à un lecteurCôté client
Appelez la méthode connectUsbReader
depuis votre application pour vous connecter à un lecteur détecté. Dès que le SDK se connecte au lecteur, le voyant d’état du lecteur devient bleu.
À la connexion, vous devez enregistrer votre lecteur en l’associant à un emplacement. Pour ce faire, créez et utilisez une configuration UsbConnectionConfiguration
avec le locationId
réglé sur l’ID de l’emplacement à associer lors de la connexion.
Ne programmez pas votre application pour appeler disconnectReader
afin d’économiser de l’énergie. Le lecteur assure une gestion efficace de l’alimentation à l’aide de son mode veille.
Privilégiez le type de connexion
Le Terminal SDK ne donne pas automatiquement la priorité à un type de connexion plutôt qu’à un autre. Si vous voulez avoir la possibilité d’alterner entre la détection de périphériques avec USB ou Bluetooth, vous pouvez implémenter cette fonctionnalité dans votre application de point de vente. Appelez discoverReaders
et définissez la discoveryMethod
dans la DiscoveryConfiguration
.
Pour alterner entre USB et Bluetooth, appelez disconnectReader
pour votre type de connexion actuel avant de lancer l’autre type. Par exemple, appelez disconnectReader
pour un lecteur connecté en Bluetooth avant d’appeler connectUsbReader
.
Gérer les déconnexions des lecteurs
Des déconnexions du lecteur peuvent parfois se produire entre votre application et le lecteur. Le lecteur peut par exemple se déconnecter de votre application si le câble USB le reliant à votre appareil est débranché. Vous pouvez simuler une déconnexion inopinée en éteignant le lecteur.
Le ReaderListener
inclut un rappel onDisconnect
qui fournit à votre application le DisconnectReason
afin de vous aider à identifier la raison pour laquelle le lecteur s’est déconnecté.
Vous pouvez gérer les déconnexions de deux manières :
Gérer la déconnexion immédiatement
Pour cette option, votre application doit implémenter le rappel UnexpectedReaderDisconnect
pour gérer manuellement la déconnexion d’un lecteur. Il s’agit du comportement par défaut du SDK.
Dans votre implémentation de ce rappel, affichez une interface utilisateur pour informer l’utilisateur que le lecteur s’est déconnecté.
Le lecteur peut se déconnecter de votre application si le câble USB le reliant à votre appareil est débranché. Pour simuler une déconnexion inopinée, éteignez le lecteur.
Tenter automatiquement de se reconnecter
Pour cette option, votre application doit définir autoReconnectOnUnexpectedDisconnect
sur « true » dans UsbConnectionConfiguration
et implémenter les rappels trouvés dans ReconnectionListener
. Vous devez également transmettre un objet autoReconnectionListener
à votre UsbConnectionConfiguration
.
Si vous tentez de vous reconnecter automatiquement, les événements suivants se produisent :
- En cas de déconnexion, le SDK tente automatiquement de se reconnecter et vous informe via
onReaderReconnectStarted
. Assurez-vous que votre application annonce que la connexion a été perdue et qu’une reconnexion est en cours.
- Vous pouvez utiliser l’objet
Cancelable
pour arrêter la tentative de reconnexion à tout moment.
- Si le SDK parvient à se reconnecter au lecteur, vous recevrez une notification
onReaderReconnectSucceeded
. Assurez-vous que votre application signale à l’utilisateur que la connexion a été restaurée et qu’il peut reprendre ses opérations habituelles. - Si le SDK ne parvient pas à se reconnecter au lecteur, vous recevrez une notification
onReaderReconnectFailed
. Assurez-vous que votre application signale à l’utilisateur qu’une déconnexion inattendue s’est produite.
Redémarrer le lecteur connecté
Les lecteurs M2 et BBPOS WisePad 3 de Stripe redémarrent automatiquement après 24 heures de fonctionnement. Vous pouvez cependant forcer le lecteur à redémarrer et réinitialiser sa minuterie de 24 heures à l’aide de l’API rebootReader
. Après cette action, le lecteur se déconnecte du SDK, puis redémarre. Si vous utilisez la reconnexion automatique, le SDK tente de rétablir la connexion avec le lecteur.
Reconnexion automatique au démarrage de l’application
Stripe Terminal ne se reconnecte pas automatiquement à un lecteur au démarrage de votre application. Vous pouvez créer un flux de reconnexion en enregistrant les ID de lecteur et en essayant de vous connecter à un lecteur connu au démarrage.
- Lorsque vous vous connectez à un lecteur, enregistrez son numéro de série dans un emplacement de stockage persistant, comme l’API Shared Preferences.
- Au lancement de votre application, vérifiez si un numéro de série enregistré se trouve dans cet emplacement persistant. Si vous en trouvez un, appelez la méthode
discoverReaders
afin que votre application puisse essayer de retrouver le lecteur. - Si le numéro de série enregistré correspond à l’un des lecteurs détectés, essayez de vous connecter à ce lecteur à l’aide de l’objet Reader correspondant renvoyé par l’appel à
discoverReaders
. Si le lecteur en question est introuvable, mettez fin au processus de recherche.
Au cours du processus de recherche et de connexion, vous pouvez afficher un message d’interface utilisateur indiquant qu’une reconnexion automatique est en cours.
Mettre à jour le logiciel du lecteurCôté client
Vous devez prendre en charge la mise à jour du lecteur depuis votre application, le lecteur ne pouvant pas se mettre à jour lui-même. Les mises à jour installées comprennent des configurations régionales qui vous assurent de répondre aux exigences des réseaux et des émetteurs de cartes, ainsi que des correctifs de sécurité. Elles sont lancées au moment de la connexion au lecteur et leur installation doit aller à son terme pour que le lecteur puisse être utilisé.
Note
L’installation des mises à jour nécessite que la batterie du lecteur soit chargée à plus de 50 %.
Mises à jour requises
Lorsque des mises à jour sont immédiatement requises pour le lecteur, le connectionStatus
du terminal bascule sur l’état ConnectionStatus.CONNECTING
pendant l’envoi des modifications. Le processus de connexion n’aboutira pas tant que la mise à jour requise n’aura pas été installée sur le lecteur.
Pour les mises à jour amenées à durer plus de 30 secondes, le ReaderListener
de votre application reçoit onStartInstallingUpdate
avec un objet ReaderSoftwareUpdate
contenant les détails de la mise à jour, dont le paramètre timeEstimate
, correspondant à la durée totale estimée.
Dans votre application, avertissez l’utilisateur qu’une mise à jour est en cours d’installation et affichez sa progression de sorte que la raison pour laquelle le processus de connexion prend plus de temps que d’habitude soit claire.
Vous pouvez annuler des mises à jour requises à l’aide de l’objet Cancelable
. Cependant, cette annulation entraînera l’échec de la connexion au lecteur. Pour les mises à jour incrémentales uniquement, aucun objet Cancelable
n’est disponible étant donné que ces mises à jour ne peuvent pas être annulées.
Mises à jour facultatives
Les mises à jour facultatives sont annoncées à votre ReaderListener
lorsque le lecteur est connecté mais n’a aucune transaction en cours. Le ReaderListener
de votre application reçoit le rappel onReportAvailableUpdate
avec l’objet ReaderSoftwareUpdate
contenant les détails de la mise à jour. Cette mise à jour est également stockée sur l’objet Reader sous le nom reader.availableUpdate
, pour être installée lors de l’appel Terminal.installAvailableUpdate
. L’objet Update inclut une estimation de la durée de la mise à jour (timeEstimate
) et la date à laquelle son installation deviendra obligatoire (requiredAt
).
Dans votre application, signalez aux utilisateurs qu’une mise à jour est disponible et affichez un message les invitant à l’installer. Pour continuer, appelez installAvailableUpdate
afin d’installer la mise à jour dans onReportAvailableUpdate
.
Pendant l’installation de la mise à jour, empêchez l’utilisateur de quitter la page de votre application et demandez-lui de garder le lecteur branché et allumé jusqu’à la fin de la mise à jour. Nous vous recommandons d’afficher un indicateur permettant à l’utilisateur de visualiser la progression de la mise à jour. Vous pouvez utiliser la méthode onReportReaderSoftwareUpdateProgress
dans votre ReaderListener
.
Une fois que la date requiredAt
est atteinte, la mise à jour facultative ne sera installée qu’après déconnexion et reconnexion du lecteur.
Vous pouvez également différer les mises à jour facultatives, mais elles deviennent obligatoires si vous ne les installez pas avant une certaine date.
Prochaines étapes
Vous avez connecté votre application au lecteur. Vous pouvez maintenant encaisser votre premier paiement avec Stripe Terminal.
Les nom et logo BBPOS et Chipper™ sont des marques ou marques déposées de BBPOS Limited aux États-Unis et/ou dans d’autres pays. Les nom et logo Verifone® sont des marques ou marques déposées de Verifone aux États-Unis et/ou dans d’autres pays. L’utilisation de ces marques n’implique aucune approbation de la part de BBPOS ou Verifone.