# Guide de migration du SDK Terminal V4 Découvrez comment migrer vers la version 4.0.0 du SDK de Stripe Terminal. Les SDK Stripe Terminal pour iOS et Android ont été mis à jour avec un certain nombre de changements majeurs au niveau des API et du comportement, dont certains nécessitent que vous mettiez à jour votre intégration avec le SDK Stripe Terminal. Nous apportons régulièrement des modifications aux mises à jour de versions majeures susceptibles d’affecter le fonctionnement ou le comportement de votre intégration, afin d’améliorer la cohérence entre nos SDK et de simplifier la logique et l’intégration de votre application. Ce guide vous présente les dernières modifications pour vous aider à mettre à niveau votre intégration. > Si vous développez une nouvelle intégration Stripe Terminal, consultez la section [concevoir une intégration](https://docs.stripe.com/terminal/designing-integration.md), pour en savoir plus sur comment démarrer. ## Migrer vers la version 4.0.0 Voici les éléments à retenir concernant les SDK de Stripe Terminal 4.0.0 pour iOS et Android : - [Enregistrer les détails de paiement après le paiement à l’échelle mondiale](https://docs.stripe.com/terminal/features/saving-payment-details/save-after-payment.md) - Les utilisateurs peuvent désormais enregistrer leurs informations de paiement après avoir effectué un paiement en dehors des États-Unis en mettant à jour le processus de collecte du consentement du client pour l’enregistrement des informations de paiement sur les appareils des points de vente. - Prise en charge des paiements des commandes passées par [correspondance et par téléphone](https://docs.stripe.com/terminal/features/mail-telephone-orders/overview.md) (MOTO) sur lecteurs intelligents (Version bêta) - Cette fonctionnalité est en version bêta. Pour faire une demande d’accès, envoyez un e-mail à [stripe-terminal-betas@stripe.com](mailto:stripe-terminal-betas@stripe.com). - Mises à jour vers la version minimale des plateformes iOS prises en charge - Active, par défaut, la reconnexion automatique du [lecteur en cas de déconnexion inattendue](https://docs.stripe.com/terminal/payments/connect-reader.md?terminal-sdk-platform=ios&reader-type=tap-to-pay#automatically-attempt-reconnection) pour les lecteurs mobiles et Tap to Pay - Consolidation des fonctionnalités de connexion des lecteurs et des rappels de déconnexion pour tous les types de lecteurs # iOS > This is a iOS for when terminal-sdk-platform is ios. View the full page at https://docs.stripe.com/terminal/references/sdk-v4-migration-guide?terminal-sdk-platform=ios. Si votre application utilise actuellement une version du SDK Terminal iOS antérieure à 4.0.0, vous devez apporter quelques modifications pour passer à une mise à niveau et accepter les paiements par carte physique dans le monde entier. Pour obtenir la liste détaillée des modifications apportées de la version 3.9.1 à la version 4.0.0, consultez le [log des modifications du SDK](https://github.com/stripe/stripe-terminal-ios/blob/master/CHANGELOG.md). ## Mettez à jour votre version minimale prise en charge vers iOS 14 ou une version plus récente Nous mettons régulièrement à jour la version minimale prise en charge de nos SDK afin de rationaliser nos efforts de support aux développeurs. Les versions 3.X existantes du SDK Terminal iOS continueront de prendre en charge les appareils fonctionnant sous *iOS 13* et versions ultérieures. ## Mettez à jour les cartes bancaires après l’intégration de PaymentIntents Si vous [enregistrez un moyen de paiement après une PaymentIntent réussie en personne](https://docs.stripe.com/terminal/features/saving-payment-details/save-after-payment.md), vous devez apporter les modifications suivantes à votre intégration : - Lors de la création de PaymentIntents Terminal, transmettez le paramètre [setup_future_usage](https://stripe.dev/stripe-terminal-ios/docs/4.0.0/Classes/SCPPaymentIntent.html#/c:objc\(cs\)SCPPaymentIntent\(py\)setupFutureUsage), qui informe Stripe que vous souhaitez effectuer des paiements futurs avec la même carte bancaire. - Vous devez également transmettre le paramètre [allow_redisplaySCPCollectConfiguration](https://stripe.dev/stripe-terminal-ios/docs/Classes/SCPCollectConfiguration.html#/c:objc\(cs\)\(py\)allowRedisplay) sur la valeur `toujours` ou de façon `limitée` dans `SCPCollectConfiguration`. Transmettez la valeur `toujours` si vous souhaitez que la carte enregistrée du client lui soit présentée dans tous les tunnels de paiement futurs, et `de façon limitée` s’il ne peut l’utiliser que dans le contexte de l’utilisation initialement visée, comme un abonnement. En savoir plus sur l’[enregistrement des informations de paiement après un paiement](https://docs.stripe.com/terminal/features/saving-payment-details/save-after-payment.md) ## Mise à jour des cartes enregistrées sans paiement grâce à l’intégration de SetupIntents Pour garantir une intégration cohérente entre les SetupIntents et les PaymentIntents, ainsi qu’entre les transactions en personne et en ligne, nous avons supprimé, dans la `collectSetupIntentPaymentMethod` de `SCPTerminal`, le paramètre `customerConsentCollected` qui était auparavant requis pour toutes les transactions SetupIntent, et nous l’avons remplacé par le paramètre `allowRedisplay`. En savoir plus sur l’[épargne directe sans facturation](https://docs.stripe.com/terminal/features/saving-payment-details/save-directly.md). ## Adapter votre utilisation de discoverReaders - Nous avons ajouté une nouvelle valeur d’énumération, `discovering`à [SCPConnectionStatus ](https://stripe.dev/stripe-terminal-ios/docs/Enums/SCPConnectionStatus.html) pour représenter le moment où la détection du lecteur est en cours. Assurez-vous que votre intégration peut gérer ce nouvel état et fournir des informations pertinentes à vos clients. - Nous avons amélioré la gestion de plusieurs opérations de détection simultanée de lecteurs. Auparavant, appeler [discoverReadersSCPTerminal](https://stripe.dev/stripe-terminal-ios/docs/Classes/SCPTerminal.html#/c:objc\(cs\)\(im\)discoverReaders:delegate:completion:) plusieurs fois mettait en file d’attente les opérations. Désormais, lorsqu’un nouveau [discoverReadersSCPTerminal(im)](https://stripe.dev/stripe-terminal-ios/docs/Classes/SCPTerminal.html#/c:objc\(cs\)discoverReaders:delegate:completion:) est appelé alors qu’un existant est déjà en cours, le SDK annule l’opération en cours et renvoie une erreur [SCPError CanceledDueToIntegrationError](https://stripe.dev/stripe-terminal-ios/docs/Errors.html#/c:@SCPErrorNewDiscoveryRequested). La nouvelle opération discoverReaders démarre alors immédiatement. - La détection de lecteurs intelligents et de lecteurs Tap to Pay appelle désormais le bloc d’achèvement `discoverReaders` à la fin de l’opération. Ce changement reflète le fait que la détection de ces types de lecteurs n’est pas une opération de longue durée. - Nous avons corrigé un bug qui faisait fortement référence au [SCPDiscoveryDelegate](https://stripe.dev/stripe-terminal-ios/docs/Protocols/SCPDiscoveryDelegate.html) dans le SDK. Assurez-vous que votre application fait bien référence à votre délégué pour recevoir les événements de détection. ## Mettez à jour l’utilisation des connexions de votre lecteur - Pour garantir un modèle d’intégration cohérent entre la détection et la connexion du lecteur, nous avons consolidé toutes les méthodes de connexion du lecteur précédentes (`connectBluetoothReader`, `connectInternetReader`, `connectLocalMobileReader`) dans [connectReader](https://stripe.dev/stripe-terminal-ios/docs/Classes/SCPTerminal.html#/c:objc\(cs\)SCPTerminal\(im\)connectReader:delegate:connectionConfig:completion:). Le type de connexion exact est toujours déterminé par la configuration de connexion transmise. - Pour les lecteurs mobiles et les lecteurs Tap to Pay, le paramètre `ReaderDelegate` a été supprimé de la méthode `connectReader` et déplacé à la place dans `connectionConfig`, remplaçant `SCPReconnectionDelegate`. À l’instar des autres types de lecteurs, le paramètre `InternetConnectionConfiguration` des lecteurs intelligents s’attend désormais à ce qu’un paramètre `InternetReaderDelegate` lui soit transmis, ce qui permet d’alerter votre système d’intégration des événements, y compris lorsqu’un lecteur se déconnecte. | Type de lecteur | Configuration de la connexion | Lecteur délégué | | -------------------- | ----------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | | Lecteur mobile | SCPBluetoothConnectionConfiguration | [SCPMobileReaderDelegate](https://stripe.dev/stripe-terminal-ios/docs/4.0.0/Protocols/SCPMobileReaderDelegate.html) | | Lecteur intelligent | SCPInternetConnectionConfiguration | [SCPInternetReaderDelegate](https://stripe.dev/stripe-terminal-ios/docs/4.0.0/Reader.html#/c:objc\(pl\)SCPInternetReaderDelegate) | | Tap to Pay | SCPTapToPayConnectionConfiguration | [SCPTapToPayReaderDelegate](https://stripe.dev/stripe-terminal-ios/docs/4.0.0/Protocols/SCPTapToPayReaderDelegate.html) | ### Avant #### Swift ```swift // Call `connectBluetoothReader` with the selected reader and a connection config // to register to a location as set by your app. let connectionConfig: BluetoothConnectionConfiguration do { connectionConfig = try BluetoothConnectionConfigurationBuilder(locationId: ""{{LOCATION_ID}}"").build() } catch { // Handle the error building the connection configuration return } Terminal.shared.connectBluetoothReader(selectedReader, delegate: readerDelegate, connectionConfig: connectionConfig) { reader, error in if let reader = reader { print("Successfully connected to reader: \(reader)") } else if let error = error { print("connectBluetoothReader failed: \(error)") } } ``` ### Après #### Swift ```swift // Call `connectReader` with the selected reader and a connection config // to register to a location as set by your app. var connectionConfig: BluetoothConnectionConfiguration do { connectionConfig = try BluetoothConnectionConfigurationBuilder(delegate: yourMobileReaderDelegate, locationId: ""{{LOCATION_ID}}"") .build() } catch { // Handle the error building the connection configuration return } Terminal.shared.connectReader(selectedReader, connectionConfig: connectionConfig) { reader, error in if let reader = reader { print("Successfully connected to reader: \(reader)") } else if let error = error { print("connectReader failed: \(error)") } } ``` Pour plus de détails, consultez notre documentation sur la [connexion à un lecteur](https://docs.stripe.com/terminal/payments/connect-reader.md?terminal-sdk-platform=ios&reader-type=bluetooth#connect-reader). ## La reconnexion automatique est désormais activée par défaut pour les lecteurs mobiles et Tap to Pay - Pour augmenter la résilience de votre intégration Terminal avec les lecteurs mobiles et Tap to Pay, nous avons activé la [reconnexion automatique](https://docs.stripe.com/terminal/payments/connect-reader.md?terminal-sdk-platform=ios&reader-type=bluetooth#handle-disconnects) par défaut lorsqu’un lecteur se déconnecte de manière inattendue. - Nous vous recommandons d’afficher des notifications dans votre application pour informer les utilisateurs de l’état du lecteur tout au long du processus de reconnexion. Pour gérer les méthodes de reconnexion des lecteurs, nous avons supprimé le `SCPReconnectionDelegate`. Ses responsabilités ont été intégrées dans les ReaderDelegate respectifs. Utilisez le `MobileReaderDelegate` pour les lecteurs mobiles et `TapToPayReaderDelegate` pour les lecteurs Tap to Pay afin de gérer les événements de reconnexion. - Si vous avez implémenté votre propre logique de reconnexion du lecteur et que vous souhaitez conserver ce comportement, vous pouvez désactiver la reconnexion automatique en définissant le paramètre [setAutoReconnectOnUnexpectedDisconnect](https://stripe.dev/stripe-terminal-ios/docs/Classes/SCPBluetoothConnectionConfigurationBuilder.html#/c:objc\(cs\)SCPBluetoothConnectionConfigurationBuilder\(im\)setAutoReconnectOnUnexpectedDisconnect:) sur `false`. ### Avant #### Swift ```swift import StripeTerminal extension ReaderViewController: ReconnectionDelegate { // MARK: ReconnectionDelegate func terminal(_ terminal: Terminal, didStartReaderReconnect cancelable: Cancelable) { // 1. Notified at the start of a reconnection attempt // Use cancelable to stop reconnection at any time } func terminalDidSucceedReaderReconnect(_ terminal: Terminal) { // 2. Notified when reader reconnection succeeds // App is now connected } func terminalDidFailReaderReconnect(_ terminal: Terminal) { // 3. Notified when reader reconnection fails // App is now disconnected } } ``` ### Après #### Swift ```swift import StripeTerminal extension ReaderViewController: MobileReaderDelegate { // MARK: MobileReaderDelegate func reader(_ reader: Reader, didStartReconnect cancelable: Cancelable, disconnectReason: DisconnectReason) { // 1. Notified at the start of a reconnection attempt // Use cancelable to stop reconnection at any time } func readerDidSucceedReconnect(_ reader: Reader) { // 2. Notified when reader reconnection succeeds // App is now connected } func readerDidFailReconnect(_ reader: Reader) { // 3. Notified when reader reconnection fails // App is now disconnected } } ``` Pour plus de détails et d’extrait de code, consultez la page [Tentative automatique de reconnexion](https://docs.stripe.com/terminal/payments/connect-reader.md?terminal-sdk-platform=ios&reader-type=tap-to-pay#automatically-attempt-reconnection). ## Mettez à jour la gestion de la déconnexion des lecteurs - Pour recevoir une notification de la déconnexion d’un lecteur, nous avons consolidé les rappels de déconnexion du lecteur pour tous les types de lecteurs en supprimant le paramètre `terminal:didReportUnexpectedReaderDisconnect:` à partir de `SCPTerminalDelegate`. Utilisez `reader:didDisconnect:` dans le cadre des ReaderDelegates pour être recevoir une notification de la déconnexion d’un lecteur. Pour les lecteurs mobiles, le paramètre [SCPDisconnectReason](https://stripe.dev/stripe-terminal-ios/docs/Enums/SCPDisconnectReason.html) peut aider à identifier la raison de la déconnexion. Lorsque la reconnexion automatique est activée, les deux méthodes [`lecteurDidFailReconnect:`](https://stripe.dev/stripe-terminal-ios/docs/4.0.0/Protocols/SCPReaderDelegate.html#/c:objc\(pl\)SCPlecteurDelegate\(im\)lecteurDidFailReconnect:) et [`reader:didDisconnect:`](https://stripe.dev/stripe-terminal-ios/docs/4.0.0/Protocols/SCPReaderDelegate.html#/c:objc\(pl\)SCPReaderDelegate\(im\)reader:didDisconnect:) sont appelées, si le SDK ne parvient pas à se reconnecter au lecteur et qu’il se déconnecte. ### Avant #### Swift ```swift import StripeTerminal class ReaderViewController: UIViewController, TerminalDelegate { override func viewDidLoad() { super.viewDidLoad() Terminal.shared.delegate = self } // ... // MARK: TerminalDelegate func terminal(_ terminal: Terminal, didReportUnexpectedReaderDisconnect reader: Reader) { // Consider displaying a UI to notify the user and start rediscovering readers } } ``` ### Après #### Swift ```swift import StripeTerminal class ReaderViewController: UIViewController, MobileReaderDelegate { override func viewDidLoad() { super.viewDidLoad() // Set the reader delegate when connecting to a reader } // ... func reader(_ reader: Reader, didDisconnect reason: DisconnectReason) { // Consider displaying a UI to notify the user and start rediscovering readers } } ``` Pour en savoir plus, consultez notre documentation sur la [gestion manuelle des déconnexions](https://docs.stripe.com/terminal/payments/connect-reader.md?terminal-sdk-platform=ios&reader-type=tap-to-pay#handle-the-disconnect-manually). ## Mettez à jour votre intégration de l’acceptation des paiements - Vous pouvez désormais annuler `confirmPaymentIntent` en utilisant l’objet `Cancelable` renvoyé. Ceci est utile pour les paiements par QR code, dont le processus de confirmation est asynchrone. De même, les paramètres `confirmSetupIntent` et `confirmRefund` peuvent désormais être annulés. - Nous avons amélioré la sécurité des types et la cohérence entre les SDK mobiles en mettant à jour la façon dont les `paymentMethodTypes` sont spécifiés dans `SCPPaymentIntentParameters` et `SCPSetupIntentParameters`. Auparavant, ce paramètre était représenté par un tableau de chaînes (par exemple, [« card_present »]). Il utilise désormais les valeurs énumérées de `SCPPaymentMethodType`. - Pour améliorer le flux d’annulation des PaymentIntents et des SetupIntents, l’appel de `Terminal::cancelPaymentIntent` ou `Terminal::cancelSetupIntent` annule également tout traitement de paiement en cours. Il n’est plus nécessaire d’annuler séparément les opérations de paiement telles que `.collectPaymentMethod` avant d’annuler la PaymentIntent. - La valeur null peut désormais être attribuée à `SCPSetupIntent.stripeId`, par cohérence avec `SCPPaymentIntent.stripeId`. Bien que la valeur `stripeId` soit toujours présente, assurez-vous que votre code gère en toute sécurité dans le cas où `SCPSetupIntent.stripeId` pourrait être `null` afin d’éviter une erreur de compilation. ## Adapter l’utilisation pour le renommage et la fin de prise en charge - [`BluetoothReaderDelegate`](https://stripe.dev/stripe-terminal-ios/3.9.0/Protocols/SCPBluetoothReaderDelegate.html) a été renommé en [`MobileReaderDelegate`](https://stripe.dev/stripe-terminal-ios/Protocols/SCPMobileReaderDelegate.html). - Dans `SCPReaderSoftwareUpdate,` nous avons renommé `SCPUpdateTimeEstimate` en `SCPUpdateDurationEstimate` et `estimatedUpdateTime` en `durationEstimate` pour mieux représenter leur intention. - Dans `SCPOfflineDetails`, qui représente les informations de paiement disponibles lorsqu’un paiement est créé ou confirmé hors ligne, nous avons remplacé le nom du paramètre `collectedAt` correspondant à l’heure à laquelle le paiement hors ligne a eu lieu par`storedAt`, afin de nous conformer aux conventions de dénomination du SDK Terminal pour Android. - Nous avons renommé « local mobile » et « apple built in » en « Tap To Pay » dans tous les noms de fonctions et codes d’erreur du SDK. # Android > This is a Android for when terminal-sdk-platform is android. View the full page at https://docs.stripe.com/terminal/references/sdk-v4-migration-guide?terminal-sdk-platform=android. Si votre application utilise actuellement une version du SDK Terminal pour Android antérieure à 4.0.0, vous devrez procéder à quelques modifications pour effectuer la mise à niveau et accepter les paiements par carte physique dans le monde entier. Pour obtenir une liste détaillée des modifications apportées entre la version 3.10.0 et la version 4.0.0, veuillez consulter le [log des modifications du SDK](https://github.com/stripe/stripe-terminal-android/blob/master/CHANGELOG.md). ## Mettez à jour vos cartes bancaires après l’intégration PaymentIntents Si vous [enregistrez un moyen de paiement après une PaymentIntent réussie en personne](https://docs.stripe.com/terminal/features/saving-payment-details/save-after-payment.md), vous devez apporter les modifications suivantes à votre intégration : - Lors de la création de PaymentIntents Terminal, transmettez le paramètre [setup_future_utilisation](https://stripe.dev/stripe-terminal-android/external/com.stripe.stripeterminal.external.models/-payment-intent/index.html#-745150436%2FProperties%2F-1219334616), qui informe Stripe que vous souhaitez effectuer des paiements futurs avec la même carte. - Vous devez également transmettre le paramètre [allow_redisplay](https://stripe.dev/stripe-terminal-android/external/com.stripe.stripeterminal.external.models/-collect-configuration/index.html#-74877977%2FProperties%2F-1219334616) sur la valeur `TOUJOURS` ou `LIMITÉ` dans `CollectConfiguration`. Transmettez la valeur `TOUJOURS` si vous souhaitez lui présenter la carte enregistrée du client dans tous les flux des paiements futurs, et `LIMITÉ` s’il ne peut l’utiliser que dans le contexte de l’utilisation initialement visée, comme un abonnement. En savoir plus sur l’[enregistrement des cartes après un paiement](https://docs.stripe.com/terminal/features/saving-payment-details/save-after-payment.md) ## Mettez à jour vos cartes d’épargne sans paiement grâce à l’intégration SetupIntents. Pour garantir une intégration cohérente entre les SetupIntents et les PaymentIntents, ainsi qu’entre les transactions en personne et en ligne, nous avons supprimé, dans la [`collectSetupIntentPaymentMethod`](https://stripe.dev/stripe-terminal-android/core/com.stripe.stripeterminal/-terminal/index.html#915185703%2FFunctions%2F-1814817128) de `Terminal`, le paramètre `customerConsentCollected` qui était auparavant requis pour toutes les transactions SetupIntent, et nous l’avons remplacé par le paramètre `allowRedisplay`. En savoir plus sur l’[épargne directe sans facturation](https://docs.stripe.com/terminal/features/saving-payment-details/save-directly.md). ## Adapter votre utilisation de discoverReaders - Nous avons ajouté une nouvelle valeur d’énumération, `DISCOVERING`, à [ConnectionStatus](https://stripe.dev/stripe-terminal-android/external/com.stripe.stripeterminal.external.models/-connection-status/index.html) pour indiquer lorsque la détection du lecteur est en cours. Assurez-vous que votre intégration peut gérer ce nouvel état et fournir les informations pertinentes à vos clients. - Nous avons amélioré la gestion des opérations de détection de plusieurs lecteurs simultanés. Auparavant, appeler [Terminal::discoverReaders](https://stripe.dev/stripe-terminal-android/core/com.stripe.stripeterminal/-terminal/index.html#-307737612%2FFunctions%2F-1814817128) plusieurs fois mettait en file d’attente les opérations, ce qui, selon nous, n’était pas souhaitable. Désormais, lorsqu’un nouveau `Terminal::discoverReaders` est appelé alors qu’un existant est déjà en cours, le SDK annule l’opération en cours et renvoie une erreur [CANCELED_DUE_TO_INTEGRATION_ERROR](https://stripe.dev/stripe-terminal-android/external/com.stripe.stripeterminal.external.models/-terminal-error-code/-c-a-n-c-e-l-e-d_-d-u-e_-t-o_-i-n-t-e-g-r-a-t-i-o-n_-e-r-r-o-r/index.html). La nouvelle opération discoverReaders démarre alors immédiatement. - La détection de lecteurs intelligents et de lecteurs Tap to Pay appelle désormais le rappel de fin d’exécution `Terminal::discoverReaders` à la fin de l’opération. Ce changement reflète le fait que la détection de lecteurs pour ces types de lecteurs n’est pas une opération de longue durée. ## Mettez à jour l’utilisation des connexions de votre lecteur - Pour garantir un modèle d’intégration cohérent entre la détection et la connexion du lecteur, nous avons consolidé toutes les méthodes de connexion du lecteur (`connectBluetoothReader`, `connectUsbReader`, `connectInternetReader`, `connectLocalMobileReader`, `connectHandoffReader`) dans [Terminal::connectReader](https://stripe.dev/stripe-terminal-android/core/com.stripe.stripeterminal/-terminal/index.html#1656325082%2FFunctions%2F-1814817128). Le type de connexion spécifique est toujours déterminé par la configuration de connexion fournie. - Pour les lecteurs mobiles, le paramètre `readerListener` a été supprimé des anciennes méthodes `connectBluetoothReader` et `connectUsbReader`, et déplacé dans l’objet `ConnectionConfiguration` respectif, remplaçant `ReaderReconnectionListener`. Pour les lecteurs Tap to Pay, l’objet `TapToPayConnectionConfiguration` intègre désormais un paramètre `TapToPayReaderListener`, qui remplace `ReaderReconnectionListener`. - Comme pour les autres types de lecteurs, la `configuration InternetConnectionConfiguration` des lecteurs intelligents prévoit désormais également la transmission d’un [`InternetReaderListener`](https://stripe.dev/stripe-terminal-android/external/com.stripe.stripeterminal.external.callable/-internet-reader-listener/index.html), qui alerte votre intégration des événements, y compris les déconnexions du lecteur. - Pour les [applications sur appareils](https://docs.stripe.com/terminal/features/apps-on-devices/overview.md#pos-stripe-device) en mode transfert, [`HandoffReaderListener`](https://stripe.dev/stripe-terminal-android/external/com.stripe.stripeterminal.external.callable/-handoff-reader-listener/index.html) a été supprimé de l’ancienne méthode `connectHandoffReader` en tant que paramètre et déplacé dans l’objet `HandoffConnectionConfiguration`. | Type de lecteur | Configuration de la connexion | Écouteur de lecteur | | ------------------------------ | ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Lecteur mobile | `BluetoothConnectionConfiguration` | [MobileReaderListener](https://stripe.dev/stripe-terminal-android/external/com.stripe.stripeterminal.external.callable/-mobile-reader-listener/index.html) | | Lecteur intelligent | `InternetConnectionConfiguration` | [InternetReaderListener](https://stripe.dev/stripe-terminal-android/com.stripe.stripeterminal.external.callable/-internet-reader-listener/index.html) | | Tap to Pay | `TapToPayConnectionConfiguration` | [TapToPayReaderListener](https://stripe.dev/stripe-terminal-android/external/com.stripe.stripeterminal.external.callable/-tap-to-pay-reader-listener/index.html) | | Applications sur des appareils | `HandoffConnectionConfiguration` | [HandoffReaderListener](https://stripe.dev/stripe-terminal-android/external/com.stripe.stripeterminal.external.callable/-handoff-reader-listener/index.html) | ### Avant #### Kotlin ```kotlin val connectionConfig = ConnectionConfiguration.BluetoothConnectionConfiguration( ""{{LOCATION_ID}}"" ) Terminal.getInstance().connectBluetoothReader( selectedReader, connectionConfig, readerListener, object : ReaderCallback { override fun onSuccess(reader: Reader) { // Placeholder for handling successful operation } override fun onFailure(e: TerminalException) { // Placeholder for handling exception } } ) ``` ### Après #### Kotlin ```kotlin // Implement your MobileReaderListener val mobileReaderListener = yourMobileReaderListener val autoReconnectOnUnexpectedDisconnect = true val connectionConfig = BluetoothConnectionConfiguration( ""{{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 } } ) ``` Pour en savoir plus, consultez la section [connexion à un lecteur](https://docs.stripe.com/terminal/payments/connect-reader.md?terminal-sdk-platform=android&reader-type=bluetooth#connect-reader) ## La reconnexion automatique est désormais activée par défaut pour les lecteurs mobiles et Tap to Pay - Pour augmenter la résilience de votre intégration Terminal avec les lecteurs mobiles et Tap to Pay, nous avons activé la [reconnexion automatique](https://docs.stripe.com/terminal/payments/connect-reader.md?terminal-sdk-platform=android&reader-type=bluetooth#handle-disconnects) par défaut lorsque le lecteur se déconnecte de manière inattendue. - Nous vous recommandons d’afficher des notifications dans votre application pour informer les utilisateurs de l’état du lecteur tout au long du processus de reconnexion. Pour gérer les méthodes de reconnexion des lecteurs, le `ReaderReconnectionListener` a été hérité par les ReaderListeners respectifs. Utilisez `MobileReaderListener` pour les lecteurs mobiles et `TapToPayReaderListener` pour les lecteurs Tap to Pay afin de gérer les événements de reconnexion. - Nous avons supprimé le paramètre `ReaderReconnectionListener` des configurations de connexion : `LocalMobileConnectionConfiguration`, `BluetoothConnectionConfiguration` et `UsbConnectionConfiguration`, et l’avons remplacé par le paramètre `ReaderListener` approprié. Si vous avez implémenté votre propre logique de reconnexion du lecteur et que vous souhaitez conserver ce comportement, vous pouvez désactiver la reconnexion automatique en définissant [autoReconnectOnUnexpectedDisconnect](https://stripe.dev/stripe-terminal-android/external/com.stripe.stripeterminal.external.models/-connection-configuration/-bluetooth-connection-configuration/index.html#1748469061%2FProperties%2F-1219334616) sur la valeur `false`. ### Avant #### Kotlin ```kotlin class CustomReaderReconnectionListener : ReaderReconnectionListener { 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 } } ``` ### Après #### Kotlin ```kotlin 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 en savoir plus, consultez la page [Tentative automatique de reconnexion](https://docs.stripe.com/terminal/payments/connect-reader.md?terminal-sdk-platform=android&reader-type=tap-to-pay#automatically-attempt-reconnection). ## Mettez à jour la gestion de la déconnexion des lecteurs - Pour recevoir une notification lorsqu’un lecteur se déconnecte, nous avons regroupé les rappels de déconnexion des lecteurs pour tous les types de lecteurs en supprimant `TerminalListener::onUnexpectedReaderDisconnect`. À l’avenir, implémentez le paramètre `onDisconnect` sur l’un des écouteurs suivants pour recevoir une notification des déconnexions des lecteurs correspondants : `InternetReaderListener`, `MobileReaderListener`, `TapToPayReaderListener`, ou `HandoffReaderListener`. Pour les lecteurs mobiles, le paramètre [`DisconnectReason`](https://stripe.dev/stripe-terminal-android/external/com.stripe.stripeterminal.external.models/-disconnect-reason/index.html) peut aider à identifier la raison de la déconnexion. Lorsque la reconnexion automatique est activée, les méthodes `onDisconnect` et [`on ReaderReconnectFailed`](https://stripe.dev/stripe-terminal-android/external/com.stripe.stripeterminal.external.callable/-reader-reconnection-listener/on-reader-reconnect-failed.html) sont appelées si le SDK ne parvient pas à se reconnecter au lecteur et qu’il se déconnecte. ### Avant #### Kotlin ```kotlin class ReaderActivity : AppCompatActivity(), TerminalListener { // ... Terminal.getInstance().setTerminalListener(this) // ... override fun onUnexpectedReaderDisconnect(reader: Reader) { // Consider displaying a UI to notify the user and start rediscovering readers } // ... } ``` ### Après #### Kotlin ```kotlin class ReaderActivity : AppCompatActivity(), MobileReaderListener { // ... override fun onDisconnect(reason: DisconnectReason) { // Consider displaying a UI to notify the user and start rediscovering readers } // ... } ``` Pour plus de détails, consultez la page [gestion manuelle des déconnexions](https://docs.stripe.com/terminal/payments/connect-reader.md?terminal-sdk-platform=android&reader-type=tap-to-pay#handle-the-disconnect-manually). ## Mettez à jour votre intégration de l’acceptation des paiements - Vous pouvez désormais annuler le paramètre `Terminal::confirmPaymentIntent` en utilisant l’objet `Cancelable` renvoyé. Ceci est utile pour les paiements par QR code, dont le processus de confirmation est asynchrone. De même, les paramètres `Terminal::confirmSetupIntent` et `Terminal::confirmRefund` peuvent désormais être annulés. - Pour améliorer le flux d’annulation des PaymentIntents et des SetupIntents, l’appel à `Terminal::cancelPaymentIntent` ou `Terminal::cancelSetupIntent` annule également tout traitement de paiement en cours. Il n’est plus nécessaire d’annuler séparément les opérations de paiement telles que `Terminal::collectPaymentMethod` avant d’annuler le PaymentIntent. - La valeur null peut désormais être attribuée à `SetupIntent.id`, par cohérence avec `PaymentIntent.id`. Bien que la valeur `id`soit toujours présente, assurez-vous que votre code gère en toute sécurité le cas où `SetupIntent.id` pourrait être `null` afin d’éviter une erreur de compilation. ## Mettez à jour la gestion des erreurs - Nous avons déplacé `TerminalException.TerminalErrorCode` vers une énumération autonome, `TerminalErrorCode`. Veillez à Mettez à jour les déclarations d’importation et la définition du code d’erreur de Terminal pour maintenir la fonctionnalité. - Nous avons ajouté un nouveau code d’erreur `TerminalErrorCode.GENERIC_READER_ERROR`, qui peut se produire lorsque le SDK n’est pas à jour et ne peut pas reconnaître l’erreur renvoyée par le lecteur intelligent. Pour rectifier cette erreur, mettez à jour votre SDK Terminal. - Pour Tap to Pay sur Android, `Terminal::collectPaymentMethod` et `Terminal::collectSetupIntentPaymentMethod` expirent désormais au bout de 60 secondes pour les transactions Tap to Pay sur Android. Une `TerminalException` est levée avec le code d’erreur `TerminalErrorCode.CARD_READ_TIMED_OUT`. - Pour Tap to Pay sur Android, lorsque la collecte du code PIN est demandée pour un paiement, une `TerminalException` est levée avec le code d’erreur `FEATURE_NOT_ENABLED_ON_ACCOUNT` au lieu de `DECLINED_BY_STRIPE_API`avec une erreur `ONLINE_OR_OFFLINE_PIN_REQUIRED` `ApiError`. ## Mise à jour de l’utilisation pour le renommage et la refactorisation - `ReaderListener` a été renommé en [`MobileReaderListener`](https://stripe.dev/stripe-terminal-android/external/com.stripe.stripeterminal.external.callable/-mobile-reader-listener/index.html). - Nous avons renommé le paramètre `allowedPaymentMethodTypes` en `paymentMethodTypes` dans les constructeurs `PaymentIntentParameters.Builder` et `SetupIntentParameter.Builder`. - Dans `ReaderSoftwareUpdate`, nous avons renommé `UpdateTimeEstimate` en `UpdateDurationEstimate` et `estimatedUpdateTime`en `durationEstimate` afin de mieux refléter leur intention. - Nous avons converti les références `java.util.Date` en horodatages en millisecondes pour les champs suivants : `ReaderSoftwareUpdate::requiredAt`, `OfflineDetails::storedAt` et `OfflineSetupIntentDetails::storedAt`. Assurez-vous que votre application interprète correctement ces horodatages. - Les champs de l’objet `Location` ne sont plus modifiables. ## Mettez à jour l’intégration de Tap to Pay sur Android - Les coordonnées Maven pour la fonctionnalité Tap to Pay sur Android ont changé pour devenir `com.stripe:stripeterminal-taptopay:4.0.0`. Mettez à jour vos dépendances pour pointer vers le nouveau nom de l’artefact. L’ancien ne sera plus mis à jour. - Nous avons renommé tous les noms de fonctions et de champs de `LocalMobile` en `TapToPay`. Par exemple, le champ `LocalMobileDiscoveryConfiguration` a été renommé en `TapToPayDiscoveryConfiguration`. - `TapToPayConnectionConfiguration` prend désormais en charge un paramètre `TapToPayReaderListener`. Cet écouteur hérite des événements de `ReaderReconnectionListener` et de `ReaderDisconnectionListener`, fournissant ainsi un mécanisme unifié pour la gestion des événements du lecteur. - Nous avons renommé le processus d’application en arrière-plan utilisé pour collecter les transactions Tap to Pay afin d’utiliser l’identifiant de votre application, suivi du suffixe `:stripetaptopay`.