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.
Les lecteurs connectés par Bluetooth sont des appareils Bluetooth LE. Ils collectent les informations de paiement mais s’appuient sur un appareil mobile associé pour la communication avec Stripe.
Suivez ces étapes pour connecter votre application à un lecteur de terminal à l’aide du Bluetooth :
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
Tout d’abord, mettez le lecteur en marche. Puis, depuis votre application, recherchez les lecteurs connectés par Bluetooth disponibles à proximité à l’aide de la méthode discoverReaders.
Proximité Bluetooth * BBPOS Chipper 2X BT uniquement
Les filtres de proximité Bluetooth analysent les résultats pour renvoyer le lecteur le plus proche. Des voyants multicolores clignotent alors sur le lecteur détecté, ce qui permet à votre utilisateur de l’identifier facilement parmi de nombreux autres lecteurs. Une fois que le SDK a détecté un lecteur, il ne se connectera pas à un lecteur plus proche, à moins de désactiver le lecteur détecté.
Notez que lorsque vous utilisez la proximité Bluetooth, le SDK renvoie deux fois le lecteur à votre application. La première fois, votre application reçoit un objet Reader
contenant uniquement le numéro de série du lecteur. Après un bref délai, votre application reçoit le même objet Reader
comportant de nouvelles informations, telles que le niveau de la batterie du lecteur.
Nous vous recommandons d’afficher le lecteur détecté dans l’interface utilisateur de votre application, ce qui permet à l’utilisateur de confirmer la connexion au lecteur ou de l’annuler s’il ne souhaite pas utiliser ce lecteur.
Scan Bluetooth
Le scan Bluetooth recherche tous les lecteurs les plus proches et renvoie à votre application une liste de lecteurs disponibles. Au fur et à mesure que le processus de recherche avance, le SDK continue à invoquer la méthode DiscoveryDelegate.didUpdateDiscoveredReaders
avec la dernière liste de lecteurs les plus proches.
La méthode de détection Bluetooth vous permet de définir un délai d’expiration afin de limiter la durée de détection. Cela permet d’économiser la batterie de l’appareil ou de déclencher un message d’erreur quand aucun appareil n’est trouvé.
Dans votre application mobile, nous recommandons que vous affichiez une liste des lecteurs trouvés qui se met à jour automatiquement, avec les numéros de série ou les libellés pour aider les utilisateurs à identifier leur lecteur.
Se connecter à un lecteurCôté client
Appelez la méthode connectBluetoothReader
depuis votre application pour 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 BluetoothConnectionConfiguration
avec locationId
réglé sur l’ID de l’emplacement à associer à la connexion.
Pour que votre application fonctionne en arrière-plan et reste connectée au lecteur, configurez-la pour inclure le mode d’arrière-plan.
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.
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 s’il est hors de portée ou lorsqu’il n’a plus de batterie. Vous pouvez simuler une déconnexion inopinée en éteignant le lecteur.
Le BluetoothReaderDelegate
inclut un reader:didDisconnect:
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 didReportUnexpectedReaderDisconnect
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 s’il perd sa connexion à Internet ou si sa batterie est déchargée. Pour simuler une déconnexion inattendue, éteignez le lecteur.
Tenter automatiquement de se reconnecter
Pour cette option, votre application doit définir autoReconnectOnUnexpectedDisconnect
sur true dans BluetoothConnectionConfiguration
et implémenter les rappels trouvés dans ReconnectionDelegate
. Vous devez également transmettre un autoReconnectionDelegate
à votre BluetoothConnectionConfiguration
.
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
didStartReaderReconnect
. 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.
- Vous pouvez utiliser l’objet
- Si le SDK parvient à se reconnecter au lecteur, vous recevrez une notification
didSucceedReaderReconnect
. 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
didFailReaderReconnect
. 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 connectez un lecteur, enregistrez son numéro de série dans un emplacement de stockage de données persistant, tel que l’API UserDefaults (iOS).
- Au lancement de votre application, recherchez un numéro de série enregistré dans l’emplacement de stockage persistant des données. 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.
Affichez une interface utilisateur pendant le processus de détection et de connexion pour indiquer 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 Bluetooth depuis votre application, car le lecteur ne peut pas se mettre à jour lui-même. Les mises à jour incluent des configurations régionales qui vous permettront de répondre aux nouvelles exigences des réseaux et des émetteurs de cartes, ainsi que des correctifs de sécurité. Les mises à jour obligatoires s’installent lors de la connexion au lecteur. Dans ce cas, le lecteur n’est utilisable qu’une fois la mise à jour installée.
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 devant être effectuées immédiatement sont disponibles pour le lecteur, le BluetoothReaderDelegate
de l’intégration reçoit un rappel didStartInstallingUpdate
avec un ReaderSoftwareUpdate
. Le ReaderSoftwareUpdate
fournit des informations utiles concernant la mise à jour, dont une estimation du temps d’installation requis, indiqué par estimatedUpdateTime
. Au cours du processus d’installation de la mise à jour sur le lecteur, le connectionStatus
du Terminal passe à l’état connecting
.
Votre application doit informer les utilisateurs qu’une mise à jour est en cours d’installation et en afficher la progression dans votre interface utilisateur, afin que le client sache pourquoi la connexion prend plus de temps que d’habitude.
Si la mise à jour requise échoue, Stripe communique l’erreur au BluetoothReaderDelegate
. La tentative de connexion échoue avec la même erreur, sauf si les conditions suivantes sont remplies :
- Le lecteur exécute la dernière version du logiciel pour l’emplacement au cours des 30 derniers jours.
- La version du SDK iOS est supérieure ou égale à la version
3.5.0
.
Si les conditions sont remplies, le processus de connexion aboutit, bien que la mise à jour requise soit incomplète. Lors de la prochaine connexion à ce lecteur, Stripe tente à nouveau d’effectuer la mise à jour requise jusqu’à ce qu’elle soit installée avec succès.
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 disponibles étant donné que ces mises à jour ne peuvent pas être annulées.
Mises à jour facultatives
Les mises à jour facultatives peuvent être différées, mais elles deviennent dans un second temps obligatoires passé un certain délai. Les mises à jour facultatives sont annoncées à votre BluetoothReaderDelegate
lorsque le lecteur est connecté mais qu’il n’effectue pas de transaction. Lorsqu’une mise à jour facultative est disponible, le BluetoothReaderDelegate
de votre application reçoit le rappel didReportAvailableUpdate
avec l’objet ReaderSoftwareUpdate
contenant les détails de la mise à jour. Cette mise à jour est également stockée sur l’objet Reader sous reader.availableUpdate
, et il s’agit de celle qui sera installée lors de l’appel de Terminal.installAvailableUpdate
. L’objet Update comprend une estimation de la durée de la mise à jour (estimatedUpdateTime
) 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 procéder à la mise à jour, appelez installAvailableUpdate
, qui installera la mise à jour précédemment signalée via didReportAvailableUpdate
.
Pendant la durée de la mise à jour, empêchez l’utilisateur de quitter la page de votre application et invitez-le à garder le lecteur sous la main et sous tension jusqu’au terme de l’installation. Nous vous recommandons également d’afficher un indicateur visuel de la progression de la mise à jour. Le BluetoothReaderDelegate
rapporte cette progression via la méthode didReportReaderSoftwareUpdateProgress
.
Si la date requiredAt
d’une mise à jour facultative est atteinte, celle-ci ne pourra être installée qu’après déconnexion et reconnexion du lecteur.
Pour plus d’informations sur la façon de vous assurer que votre application gère les différents types de mises à jour possibles sur un lecteur, consultez la page Test des mises à jour d’un lecteur Bluetooth.
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.