Se connecter à un lecteur

Assurez-vous que le lecteur est sous tension et connecté avec un câble USB 2.0 à l’appareil exécutant votre application, et que l’accès au lecteur connecté en USB a été autorisé.

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.

Puis, à partir de votre application, recherchez le lecteur connecté avec la méthode discoverReaders, à l’aide de UsbDiscoveryConfiguration.

class DiscoverReadersActivity : AppCompatActivity(), DiscoveryListener {
    // ...

    var discoverCancelable: Cancelable? = null

    // Action for a "Discover Readers" button
    fun discoverReadersAction() {
        val timeout = 0
        val isSimulated = false

        val config = UsbDiscoveryConfiguration(
            timeout = timeout,
            isSimulated = isSimulated
        )

        Terminal.getInstance().discoverReaders(
            config,
            this,
            object : Callback {
                override fun onSuccess() {
                    // Placeholder for handling successful operation
                }

                override fun onFailure(e: TerminalException) {
                    // Placeholder for handling exception
                }
            }
        )
    }

    override fun onUpdateDiscoveredReaders(readers: List<Reader>) {
        // In your app, display the discovered readers to the user.
        // Call `connectReader` after the user selects a reader to connect to.
    }

    // ...
}

Pour vous connecter à un lecteur détecté, appelez la méthode connectReader depuis votre application.

Vous devez enregistrer votre lecteur en l’associant à un emplacement lors de la connexion. Pour ce faire, créez et utilisez une UsbConnectionConfiguration avec le locationId défini sur l’ID de l’emplacement approprié lors de la connexion.

// Implement your MobileReaderListener
val mobileReaderListener = yourMobileReaderListener
val autoReconnectOnUnexpectedDisconnect = true

val connectionConfig = UsbConnectionConfiguration(
    
"{{LOCATION_ID}}",
    autoReconnectOnUnexpectedDisconnect,
    mobileReaderListener
)

Terminal.getInstance().connectReader(
    selectedReader,
    connectionConfig,
    object : ReaderCallback {
        override fun onSuccess(reader: Reader) {
            // Placeholder for handling successful operation
        }

        override fun onFailure(e: TerminalException) {
            // Placeholder for handling exception
        }
    }
)

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 MobileReaderListener 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é.

Lorsqu’un lecteur se déconnecte, nous tentons automatiquement une reconnexion par défaut et vous recommandons d’afficher dans votre application des notifications qui indiquent l’état du lecteur tout au long du processus.

Pour afficher des notifications dans votre application lors de la reconnexion automatique, procédez comme suit :

1. Implémentez les rappels de reconnexion du lecteur dans le MobileReaderListener.
2. Transmettez le MobileReaderListener à votre UsbConnectionConfiguration.
3. Lorsque le SDK envoie onReaderReconnectStarted à votre application, affichez un message indiquant que le lecteur a perdu la connexion et que la reconnexion est en cours.
   • Vous pouvez utiliser l’objet Cancelable pour arrêter la tentative de reconnexion à tout moment.
4. Lorsque le SDK indique que la reconnexion a réussi en envoyant onReaderReconnectSucceeded, affichez un message indiquant que la connexion a été rétablie et que le lecteur fonctionne normalement.
5. Si le SDK ne peut pas se reconnecter au lecteur et envoie à la fois onReaderReconnectFailed et onDisconnect, affichez un message indiquant qu’une déconnexion inattendue s’est produite.

class CustomMobileReaderListener : MobileReaderListener {
    // ...

    override fun onReaderReconnectStarted(reader: Reader, cancelReconnect: Cancelable, reason: DisconnectReason) {
        // 1. Notified at the start of a reconnection attempt
        // Use cancelable to stop reconnection at any time
    }

    override fun onReaderReconnectSucceeded(reader: Reader) {
        // 2. Notified when reader reconnection succeeds
        // App is now connected
    }

    override fun onReaderReconnectFailed(reader: Reader) {
        // 3. Notified when reader reconnection fails
        // App is now disconnected
    }

    // ...
}

Pour traiter vous-même les déconnexions du lecteur, vous pouvez procéder comme suit :

1. Réglez autoReconnectOnUnexpectedDisconnect sur false pendant la connexion.
2. Traitez le rappel de déconnexion pour afficher dans l’application un message avertissant l’utilisateur que le lecteur s’est déconnecté de manière inattendue et lancer la détection et la connexion du lecteur.

class ReaderActivity : AppCompatActivity(), MobileReaderListener {
    // ...

    override fun onDisconnect(reason: DisconnectReason) {
        // Consider displaying a UI to notify the user and start rediscovering readers
    }

    // ...
}

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.

Terminal.getInstance().rebootReader(
    object : Callback {
        override fun onSuccess() {
            // Reboot succeeded and the reader will disconnect.
            // If your app is using automatic reconnect the reconnect will begin.
        }

        override fun onFailure(e: TerminalException) {
            // Placeholder for handling exception
        }
    }
)

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.

1. Lorsque vous vous connectez à un lecteur, enregistrez son numéro de série dans un emplacement de stockage persistant, comme l’API Shared Preferences (Android).

1. 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.
2. 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.

Votre application doit mettre à jour les lecteurs mobiles pour appliquer les éléments suivants :

• des configurations régionales qui vous permettent de rester en règle avec les exigences des réseaux de cartes et des émetteurs
• des mises à jour de sécurité

L’installation des mises à jour obligatoires se lance lors de la connexion au lecteur. Vous ne pouvez pas utiliser le lecteur tant que la mise à jour n’est pas terminée.

Mises à jour requises

Lorsque les mises à jour immédiatement nécessaires sont disponibles pour le lecteur, le MobileReaderListener de l’intégration reçoit onStartInstallingUpdate avec un ReaderSoftwareUpdate.

ReaderSoftwareUpdate fournit les détails nécessaires de la mise à jour, y compris une estimation de la durée totale de la mise à jour, indiquée par durationEstimate.

Pendant le processus d’installation, le connectionStatus du Terminal passe à ConnectionStatus.CONNECTING pendant que la mise à jour s’installe sur le lecteur.

Votre application doit avertir les utilisateurs qu’une mise à jour est en cours d’installation et afficher sa progression dans votre interface utilisateur. Expliquez clairement pourquoi la connexion peut prendre plus de temps que d’habitude.

Si le processus de mise à jour requis échoue, Stripe communique l’erreur au MobileReaderListener avec onFinishInstallingUpdate. Vous ne pouvez pas vous reconnecter au lecteur après l’échec d’une mise à jour requise, 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 Android 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.

class ReaderActivity : AppCompatActivity(), MobileReaderListener {
    // ...

    override fun onStartInstallingUpdate(update: ReaderSoftwareUpdate, cancelable: Cancelable) {
        // Show UI communicating that a required update has started installing
    }

    override fun onReportReaderSoftwareUpdateProgress(progress: Float) {
        // Update the progress of the installation
    }

    override fun onFinishInstallingUpdate(update: ReaderSoftwareUpdate?, e: TerminalException?) {
        // Report success or failure of the update
    }

    // ...
}

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. Vous ne pouvez pas annuler les mises à jour complémentaires uniquement.

Mises à jour facultatives

Vous pouvez reporter les mises à jour facultatives jusqu’à la date indiquée, après quoi elles deviennent obligatoires. Le SDK vous informe des mises à jour facultatives via le MobileReaderListener chaque fois que le lecteur est connecté mais n’effectue pas de transaction. Si une mise à jour facultative est disponible, le MobileReaderListener de votre application reçoit le rappel onReportAvailableUpdate avec l’objet ReaderSoftwareUpdate contenant les détails de la mise à jour, y compris :

• Temps estimé pour la fin de la mise à jour (durationEstimate)
• Date après laquelle la mise à jour devient 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 précédemment signalée avec onReportAvailableUpdate, appelez Terminal.getInstance().installAvailableUpdate.

La mise à jour disponible est également stockée dans l’objet Reader sous la forme reader.availableUpdate.

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 connecté jusqu’à la fin de la procédure. Nous vous recommandons également d’afficher un indicateur visuel de la progression de la mise à jour. Le MobileReaderListener rapporte la progression de la mise à jour dans la méthode onReportReaderSoftwareUpdateProgress.

Lorsque la date requiredAt d’une mise à jour facultative est dépassée, la mise à jour est installée la prochaine fois que le lecteur est connecté.

class ReaderActivity : AppCompatActivity(), MobileReaderListener {
    // ...

    override fun onReportAvailableUpdate(update: ReaderSoftwareUpdate) {
        // An update is available for the connected reader. Show this update in your application.
        // Install this update using `Terminal.getInstance().installAvailableUpdate`.
    }

    // ...
}

Pour savoir comment vérifier si 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.