# Terminal SDK V4 移行ガイド Stripe Terminal SDK (バージョン 4.0.0) への移行方法を解説します。 Stripe Terminal iOS SDK および Android SDK が更新され、API と動作への重要な変更がいくつか行われました。その一部については Stripe Terminal SDK の統合アップグレードが必要になります。Stripe は、SDK 間の一貫性を向上させ、アプリケーションロジックと統合を効率化するために、定期的にメジャーバージョンの更新を行い、統合の機能や動作に影響を与える変更を加えています。このガイドでは、統合のアップグレードに関わる最新の変更について解説します。 > 新しい Stripe Terminal 統合を構築している場合は、始める方法について[統合の設計](https://docs.stripe.com/terminal/designing-integration.md)をご覧ください。 ## バージョン 4.0.0 への移行 Stripe Terminal iOS および Android の SDK 4.0.0 に関する変更点は、以下のとおりです。 - [決済後に決済詳細をグローバルに保存する](https://docs.stripe.com/terminal/features/saving-payment-details/save-after-payment.md) - POS デバイスに決済詳細を保存する際の顧客同意収集プロセスを更新することで、ユーザーはアメリカ以外の国でも決済後に決済詳細を保存できるようになりました。 - スマートリーダーでの[通信販売および電話注文](https://docs.stripe.com/terminal/features/mail-telephone-orders/overview.md) (MOTO) による決済のサポート (プレビュー) - この機能はプレビューです。アクセスをリクエストするには、[stripe-terminal-betas@stripe.com](mailto:stripe-terminal-betas@stripe.com) までメールでお問い合わせください。 - iOS プラットフォームのミニマムサポートバージョンの更新 - モバイルおよび Tap to Pay リーダーでは、[予期しない切断時にリーダーの自動再接続](https://docs.stripe.com/terminal/payments/connect-reader.md?terminal-sdk-platform=ios&reader-type=tap-to-pay#automatically-attempt-reconnection)をデフォルトで有効にする - リーダー接続機能と切断コールバックがすべてのリーダータイプで統合 # 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. アプリケーションで現在、4.0.0 より前のバージョンの Terminal iOS SDK を使用している場合は、アップグレードしてカード提示決済をグローバルに受け付けるには、いくつかの変更を行う必要があります。バージョン 3.9.1 から 4.0.0 への変更の詳細なリストについては、[SDK 変更ログ](https://github.com/stripe/stripe-terminal-ios/blob/master/CHANGELOG.md)をご覧ください。 ## iOS 14 以降のミニマムサポートバージョンに関する更新 Stripe は、開発者サポート業務を効率化するために SDK のミニマムサポートバージョンを定期的に更新しています。 現行の Terminal iOS SDK バージョン 3.X は、引き続き *iOS 13* 以降で動作するデバイスをサポートします。 ## PaymentIntent 統合後のカードの保存に関する更新 [対面での PaymentIntent が成功した後に決済手段を保存する場合](https://docs.stripe.com/terminal/features/saving-payment-details/save-after-payment.md)、統合で以下の更新を行う必要があります。 - Terminal PaymentIntents を作成する際に、[setup_future_usage](https://stripe.dev/stripe-terminal-ios/docs/4.0.0/Classes/SCPPaymentIntent.html#/c:objc(cs) パラメーターを渡します。これにより、今後同じカードで決済を行うことを Stripe に通知します。 - また、[allow_redisplay](https://stripe.dev/stripe-terminal-ios/docs/Classes/SCPCollectConfiguration.html#/c:objc\(cs\)SCPCollectConfiguration\(py\)allowRedisplay) を `always` または `limited` にして `SCPCollectConfiguration` に渡す必要があります。顧客の保存したカードを今後すべての決済フローで表示する場合は `always` を、サブスクリプションのような最初に設定した用途でのみ使用する場合は `limited` を渡します。 [決済後に決済詳細を保存する方法](https://docs.stripe.com/terminal/features/saving-payment-details/save-after-payment.md)をご紹介します。 ## SetupIntent 統合での決済を伴わないカードの保存に関する更新 SetupIntents と PaymentIntents、および対面取引とオンライン取引の間の統合パターンの一貫性を確保するため、`SCPTerminal` の `collectSetupIntentPaymentMethod` で、これまですべての SetupIntent 取引で必須だった `customerConsentCollected` パラメーターを削除し、`allowRedisplay` パラメーターに置き換えました。 [請求なしで直接保存する方法](https://docs.stripe.com/terminal/features/saving-payment-details/save-directly.md)をご紹介します。 ## discoverReaders の使用に関する更新 - リーダー検出の実行状況を示す新しい列挙値 `discovering` を [SCPConnectionStatus](https://stripe.dev/stripe-terminal-ios/docs/Enums/SCPConnectionStatus.html) に追加しました。統合でこの新しい状態に対応できることを確認し、関連する情報を顧客に伝達してください。 - 複数のリーダー同時検出操作の処理が改善されました。以前は、[discoverReaders](https://stripe.dev/stripe-terminal-ios/docs/Classes/SCPTerminal.html#/c:objc\(cs\)SCPTerminal\(im\)discoverReaders:delegate:completion:) を複数回呼び出すと、操作がキューに保持されていました。既存の操作がすでに進行中であるときに新しい [discoverReaders](https://stripe.dev/stripe-terminal-ios/docs/Classes/SCPTerminal.html#/c:objc\(cs\)SCPTerminal\(im\)discoverReaders:delegate:completion:) が呼び出されると、SDK は進行中の操作をキャンセルし、[SCPErrorCanceledDueToIntegrationError](https://stripe.dev/stripe-terminal-ios/docs/Errors.html#/c:@SCPErrorNewDiscoveryRequested) エラーを返します。その後、新しい discoverReaders 操作が直ちに開始します。 - スマートリーダーおよび Tap to Pay リーダーを見つけると、操作の終了時に `discoverReaders` の完了ブロックが呼び出されるようになりました。この変更は、これらのリーダータイプに対するリーダー検出が長時間実行される操作ではないことを表しています。 - SDK で [SCPDiscoveryDelegate](https://stripe.dev/stripe-terminal-ios/docs/Protocols/SCPDiscoveryDelegate.html) への参照を強く保持していたバグを修正しました。アプリケーションが、検出イベントを受信するためにデリゲートへの参照を強く保持していることを確認してください。 ## リーダー接続の利用に関する更新 - リーダーの検出と接続で一貫した統合パターンが保たれるように、以前のリーダー接続メソッド (`connectBluetoothReader`、`connectInternetReader`、`connectLocalMobileReader`) をすべて [connectReader](https://stripe.dev/stripe-terminal-ios/docs/Classes/SCPTerminal.html#/c:objc\(cs\)SCPTerminal\(im\)connectReader:delegate:connectionConfig:completion:) に統合しました。正確な接続タイプは、渡された接続設定によって決定されます。 - モバイルリーダーと Tap to Pay リーダーでは、`ReaderDelegate` パラメーターが `connectReader` メソッドから削除され、代わりに以前 `SCPReconnectionDelegate` だった `connectionConfig` に移動しました。他のリーダータイプと同様に、スマートリーダーの `InternetConnectionConfiguration` も `InternetReaderDelegate` が渡されることを想定しています。これは、リーダーの切断などのイベントを統合に警告します。 | リーダーのタイプ | 接続の設定 | リーダーデリゲート | | ---------- | ------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------- | | モバイルリーダー | SCPBluetoothConnectionConfiguration | [SCPMobileReaderDelegate](https://stripe.dev/stripe-terminal-ios/docs/4.0.0/Protocols/SCPMobileReaderDelegate.html) | | スマートリーダー | SCPInternetConnectionConfiguration | [SCPInternetReaderDelegate](https://stripe.dev/stripe-terminal-ios/docs/4.0.0/Reader.html#/c:objc\(pl\)SCPInternetReaderDelegate) | | Tap to Pay | SCPTap to PayConnectionConfiguration | [SCPTap to PayReaderDelegate](https://stripe.dev/stripe-terminal-ios/docs/4.0.0/Protocols/SCPTapToPayReaderDelegate.html) | ### 導入前 #### 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)") } } ``` ### 導入後 #### 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)") } } ``` 詳細については、[リーダーへの接続](https://docs.stripe.com/terminal/payments/connect-reader.md?terminal-sdk-platform=ios&reader-type=bluetooth#connect-reader)に関するドキュメントを参照してください。 ## モバイルリーダーと Tap to Pay リーダーで自動再接続がデフォルトで有効になりました - モバイルリーダーと Tap to Pay リーダーを使用した Terminal 統合の耐障害性を高めるために、リーダーが予期せず切断された場合の [自動再接続](https://docs.stripe.com/terminal/payments/connect-reader.md?terminal-sdk-platform=ios&reader-type=bluetooth#handle-disconnects)がデフォルトで有効になっています。 - 再接続プロセスの間、ユーザーにリーダーの状態を知らせるために、アプリに通知を表示させることをお勧めします。`SCPReconnectionDelegate` は、リーダーの再接続メソッドを処理するために削除されました。その役割は、それぞれの ReaderDelegate に統合されています。再接続イベントを処理するには、モバイルリーダーの場合 `MobileReaderDelegate` を、Tap to Pay リーダーの場合 `TapToPayReaderDelegate` を使用します。 - 独自のリーダー再接続ロジックを実装していて、この動作を維持する必要がある場合は、[setAutoReconnectOnUnexpectedDisconnect](https://stripe.dev/stripe-terminal-ios/docs/Classes/SCPBluetoothConnectionConfigurationBuilder.html#/c:objc(cs) を `false` に設定することで、自動再接続を無効にできます。 ### 導入前 #### 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 } } ``` ### 導入後 #### 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 } } ``` 詳細とコードスニペットについては、[自動的に再接続を試行する](https://docs.stripe.com/terminal/payments/connect-reader.md?terminal-sdk-platform=ios&reader-type=tap-to-pay#automatically-attempt-reconnection)を参照してください。 ## リーダー切断の処理に関する更新 - リーダーの切断時に通知を受け取るために、`SCPTerminalDelegate` から `terminal:didReportUnexpectedReaderDisconnect:` を削除して、すべてのリーダータイプの切断コールバックを統一しました。ReaderDelegates の一部として `reader:didDisconnect:` を使用すると、リーダーの切断時に通知が届きます。モバイルリーダーの場合、[SCPDisconnectReason](https://stripe.dev/stripe-terminal-ios/docs/Enums/SCPDisconnectReason.html) で切断の理由を確認できます。 自動再接続が有効になっている場合、SDK がリーダーへの再接続に失敗し、リーダーが切断されると、[`-readerDidFailReconnect:`]](https://stripe.dev/stripe-terminal-ios/docs/4.0.0/Protocols/SCPReaderDelegate.html#/c:objc(pl)SCPReaderDelegate(im)readerDidFailReconnect:) メソッドと [`reader:didDisconnect:`]](https://stripe.dev/stripe-terminal-ios/docs/4.0.0/Protocols/SCPReaderDelegate.html#/c:objc(pl)SCPReaderDelegate(im)reader:didDisconnect:) メソッドの両方が呼び出されます。 ### 導入前 #### 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 } } ``` ### 導入後 #### 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 } } ``` 詳細については、[手動で切断を処理する](https://docs.stripe.com/terminal/payments/connect-reader.md?terminal-sdk-platform=ios&reader-type=tap-to-pay#handle-the-disconnect-manually)に関するドキュメントを参照してください。 ## 決済の受け付け統合に関する更新 - 返された `Cancelable` オブジェクトを使用して `confirmPaymentIntent` をキャンセルできるようになりました。これは、確認プロセスが非同期である QR コード決済に有効です。同様に、`confirmSetupIntent` と `confirmRefund` もキャンセルできるようになりました。 - `paymentMethodTypes` の指定方法 (`SCPPaymentIntentParameters` と `SCPSetupIntentParameters`) を更新しました。これにより、型安全性とモバイル SDK 間の一貫性が改善されます。以前は、このパラメーターが文字列の配列で表記されていました ([“card_present”] など)。現在は `SCPPaymentMethodType` の列挙値が使用されています。 - `Terminal::cancelPaymentIntent` または `Terminal::cancelSetupIntent` を呼び出した場合に、実行中の決済処理がキャンセルされるようになりました。これは、PaymentIntent と SetupIntent のキャンセルフローを改善するために行われた変更です。PaymentIntent をキャンセルする前に `.collectPaymentMethod` などの決済処理を個別にキャンセルする必要はありません。 - `SCPPaymentIntent.stripeId` との一貫性を持たせるために、`SCPSetupIntent.stripeId` の null 指定が可能になりました。`stripeId` の値は引き続き有効ですが、コンパイルエラーを回避するために、`SCPSetupIntent.stripeId` が `null` になるケースをコードで安全に処理できるかご確認ください。 ## 名称変更および廃止に関する更新 - [`BluetoothReaderDelegate`]](https://stripe.dev/stripe-terminal-ios/3.9.0/Protocols/SCPBluetoothReaderDelegate.html) の名前が [`MobileReaderDelegate`]](https://stripe.dev/stripe-terminal-ios/Protocols/SCPMobileReaderDelegate.html) に変更されました。 - `SCPReaderSoftwareUpdate` で、`SCPUpdateTimeEstimate` を `SCPUpdateDurationEstimate` に、`estimatedUpdateTime` を `durationEstimate` に名前を変更しました。これにより、意図が把握しやすくなります。 - `SCPOfflineDetails` で、オフライン中に決済が作成または確認されたときに利用できる決済の詳細を表示するようにしました。オフラインの決済が発生した時間の名前を `collectedAt` から `storedAt` に変更し、Terminal Android SDK の命名規則に合わせました。 - すべての SDK の関数名とエラーコードにおいて、「local mobile」と「apple built in」の名前を「Tap to Pay」に変更しました。 # 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. アプリケーションが現在 4.0.0 より前のバージョンの Terminal Android SDK を使用している場合、更新してカードの対面決済をグローバルに受け付けるには変更がいくつか必要です。バージョン 3.10.0 から 4.0.0 への変更点のリストについては、[SDK 変更ログ](https://github.com/stripe/stripe-terminal-android/blob/master/CHANGELOG.md)をご覧ください。 ## PaymentIntent 統合後のカードの保存に関する更新 [対面での PaymentIntent が成功した後に決済手段を保存する場合](https://docs.stripe.com/terminal/features/saving-payment-details/save-after-payment.md)、統合で以下の更新を行う必要があります。 - Terminal PaymentIntents を作成する際に、[setup_future_usage](https://stripe.dev/stripe-terminal-android/external/com.stripe.stripeterminal.external.models/-payment-intent/index.html#-745150436%2FProperties%2F-1219334616) パラメーターを渡します。これにより、今後同じカードで決済を行うことが Stripe に通知されます。 - `CollectConfiguration` で [allow_redisplay](https://stripe.dev/stripe-terminal-android/external/com.stripe.stripeterminal.external.models/-collect-configuration/index.html#-74877977%2FProperties%2F-1219334616) を `ALWAYS` または `LIMITED` として渡す必要もあります。顧客の保存されたカードを今後の決済フローすべてで顧客に表示する場合は `ALWAYS` を渡し、サブスクリプションなど、最初に範囲が限定された用途でのみ使用できる場合は `LIMITED` を渡します。 [決済後のカードの保存](https://docs.stripe.com/terminal/features/saving-payment-details/save-after-payment.md)についてもっと知る。 ## SetupIntent 統合での決済を伴わないカードの保存に関する更新 SetupIntents と PaymentIntents、および対面取引とオンライン取引の間の統合パターンの一貫性を確保するため、`Terminal` の [`collectSetupIntentPaymentMethod`]](https://stripe.dev/stripe-terminal-android/core/com.stripe.stripeterminal/-terminal/index.html#915185703%2FFunctions%2F-1814817128) で、これまですべての SetupIntent 取引で必須だった `customerConsentCollected` パラメーターを削除し、`allowRedisplay` パラメーターに置き換えました。 [請求なしで直接保存する方法](https://docs.stripe.com/terminal/features/saving-payment-details/save-directly.md)をご紹介します。 ## discoverReaders の使用に関する更新 - リーダーの検出が実行されているタイミングを表す新しい列挙値 `DISCOVERING` が [ConnectionStatus](https://stripe.dev/stripe-terminal-android/external/com.stripe.stripeterminal.external.models/-connection-status/index.html) に追加されました。統合でこの新しい状態を処理し、関連情報を顧客に提供してください。 - 複数のリーダー同時検出操作の処理が改善されました。以前は、[Terminal::discoverReaders](https://stripe.dev/stripe-terminal-android/core/com.stripe.stripeterminal/-terminal/index.html#-307737612%2FFunctions%2F-1814817128) を複数回呼び出すと、操作がキューに保持されていましたが、これは望ましくないことがわかりました。既存の操作がすでに進行中に新しい `Terminal::discoverReaders` が呼び出されると、SDK は進行中の操作をキャンセルし、[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) エラーを返します。その後、新しい discoverReaders 操作は直ちに開始されます。 - スマートリーダーと Tap to Pay リーダーを検出すると、操作の終了時に `Terminal::discoverReaders` の完了コールバックが呼び出されるようになりました。この変更は、これらのリーダータイプに対するリーダー検出が長時間実行される操作ではないことを表しています。 ## リーダー接続の利用に関する更新 - リーダーの検出と接続で一貫した統合パターンが保たれるように、リーダー接続メソッド (`connectBluetoothReader`、`connectUsbReader`、`connectInternetReader`、`connectLocalMobileReader`、`connectHandoffReader`) をすべて [Terminal::connectReader](https://stripe.dev/stripe-terminal-android/core/com.stripe.stripeterminal/-terminal/index.html#1656325082%2FFunctions%2F-1814817128) に統合しました。具体的な接続タイプは、指定された接続設定によって決定されます。 - モバイルリーダーでは、`readerListener` パラメーターが以前の `connectBluetoothReader` メソッドと `connectUsbReader` メソッドから削除され、代わりにそれぞれの `ConnectionConfiguration` オブジェクトに移動し、`ReaderReconnectionListener` が置き換えられました。Tap to Pay リーダーでは、`TapToPayConnectionConfiguration` が `ReaderReconnectionListener` の代わりに `TapToPayReaderListener` パラメーターを受け取るようになりました。 - スマートリーダーの `InternetConnectionConfiguration` では、他のリーダータイプと同様に、[`InternetReaderListener`]](https://stripe.dev/stripe-terminal-android/external/com.stripe.stripeterminal.external.callable/-internet-reader-listener/index.html) が渡されることも想定されるようになりました。これにより、リーダーの切断を含むイベントの統合時に警告が送信されます。 - ハンドオフモードの [Apps on Devices](https://docs.stripe.com/terminal/features/apps-on-devices/overview.md#pos-stripe-device) の場合、[`HandoffReaderListener`]](https://stripe.dev/stripe-terminal-android/external/com.stripe.stripeterminal.external.callable/-handoff-reader-listener/index.html) はパラメーターとして以前の `connectHandoffReader` メソッドから削除され、`HandoffConnectionConfiguration` オブジェクトに移動されました。 | リーダーのタイプ | 接続の設定 | リーダーリスナー | | --------------- | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | モバイルリーダー | `BluetoothConnectionConfiguration` | [MobileReaderListener](https://stripe.dev/stripe-terminal-android/external/com.stripe.stripeterminal.external.callable/-mobile-reader-listener/index.html) | | スマートリーダー | `InternetConnectionConfiguration` | [InternetReaderListener](https://stripe.dev/stripe-terminal-android/com.stripe.stripeterminal.external.callable/-internet-reader-listener/index.html) | | Tap to Pay | `TapToPayConnectionConfiguration` | [Tap to PayReaderListener](https://stripe.dev/stripe-terminal-android/external/com.stripe.stripeterminal.external.callable/-tap-to-pay-reader-listener/index.html) | | Apps on Devices | `HandoffConnectionConfiguration` | [HandoffReaderListener](https://stripe.dev/stripe-terminal-android/external/com.stripe.stripeterminal.external.callable/-handoff-reader-listener/index.html) | ### 導入前 #### 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 } } ) ``` ### 導入後 #### 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 } } ) ``` 詳細については、[リーダーへの接続](https://docs.stripe.com/terminal/payments/connect-reader.md?terminal-sdk-platform=android&reader-type=bluetooth#connect-reader)を参照してください。 ## モバイルリーダーと Tap to Pay リーダーで自動再接続がデフォルトで有効になりました - モバイルリーダーと Tap to Pay リーダーを使用した Terminal 統合の耐障害性を高めるために、リーダーが予期せず切断された場合の[自動再接続](https://docs.stripe.com/terminal/payments/connect-reader.md?terminal-sdk-platform=android&reader-type=bluetooth#handle-disconnects)がデフォルトで有効になっています。 - 再接続プロセスの間、ユーザーにリーダーの状態を知らせるために、アプリに通知を表示させることをお勧めします。リーダーの再接続メソッドを処理するために、`ReaderReconnectionListener` はそれぞれの ReaderListeners に引き継がれています。再接続イベントを処理するには、モバイルリーダーの場合 `MobileReaderListener` を、Tap to Pay リーダーの場合 `TapToPayReaderListener` を使用します。 - `LocalMobileConnectionConfiguration`、`BluetoothConnectionConfiguration`、`UsbConnectionConfiguration` の接続設定から `ReaderReconnectionListener` パラメーターを削除し、適切な `ReaderListener` に置き換えました。 独自のリーダー再接続ロジックを実装していて、この動作を維持する必要がある場合は、[autoReconnectOnUnexpectedDisconnect](https://stripe.dev/stripe-terminal-android/external/com.stripe.stripeterminal.external.models/-connection-configuration/-bluetooth-connection-configuration/index.html#1748469061%2FProperties%2F-1219334616) を `false` に設定して自動再接続をオフにできます。 ### 導入前 #### 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 } } ``` ### 導入後 #### 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 } // ... } ``` 詳細については、[自動的に再接続を試行する](https://docs.stripe.com/terminal/payments/connect-reader.md?terminal-sdk-platform=android&reader-type=tap-to-pay#automatically-attempt-reconnection)を参照してください。 ## リーダー切断の処理に関する更新 - リーダーの切断が発生した場合に通知されるように、`TerminalListener::onUnexpectedReaderDisconnect` を削除して、すべてのリーダータイプの切断コールバックを統一しました。今後は、対応するリーダーの切断が通知されるよう、以下のリスナーのいずれかに `onDisconnect` を実装してください：`InternetReaderListener`、`MobileReaderListener`、`TapToPayReaderListener`、`HandoffReaderListener`。モバイルリーダーの場合、[`DisconnectReason`]](https://stripe.dev/stripe-terminal-android/external/com.stripe.stripeterminal.external.models/-disconnect-reason/index.html) で切断の理由を確認できます。 自動再接続が有効になっている場合、SDK がリーダーへの再接続に失敗し、リーダーが切断されると、`onDisconnect` メソッドと [`onReaderReconnectFailed`]](https://stripe.dev/stripe-terminal-android/external/com.stripe.stripeterminal.external.callable/-reader-reconnection-listener/on-reader-reconnect-failed.html) メソッドの両方が呼び出されます。 ### 導入前 #### 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 } // ... } ``` ### 導入後 #### Kotlin ```kotlin class ReaderActivity : AppCompatActivity(), MobileReaderListener { // ... override fun onDisconnect(reason: DisconnectReason) { // Consider displaying a UI to notify the user and start rediscovering readers } // ... } ``` 詳細については、[手動で切断を処理する](https://docs.stripe.com/terminal/payments/connect-reader.md?terminal-sdk-platform=android&reader-type=tap-to-pay#handle-the-disconnect-manually)を参照してください。 ## 決済の受け付け統合に関する更新 - 返された `Cancelable` オブジェクトを使用して `Terminal::confirmPaymentIntent` をキャンセルできるようになりました。これは、確認プロセスが非同期である QR コード決済に有効です。同様に、`Terminal::confirmSetupIntent` と `Terminal::confirmRefund` もキャンセルできるようになりました。 - `Terminal::cancelPaymentIntent` または `Terminal::cancelSetupIntent` を呼び出した場合に、実行中の決済処理がキャンセルされるようになりました。これは、PaymentIntent と SetupIntent のキャンセルフローを改善するために行われた変更です。PaymentIntent をキャンセルする前に `Terminal::collectPaymentMethod` などの決済処理を個別にキャンセルする必要はありません。 - `PaymentIntent.id` との一貫性を持たせるために、`SetupIntent.id` の null 指定が可能になりました。`id` の値は引き続き表示されますが、コンパイルエラーを回避するために、`SetupIntent.id` が `null` になるケースをコードで安全に処理できるかご確認ください。 ## エラー処理に関する更新 - `TerminalException.TerminalErrorCode` をスタンドアロンの列挙型 `TerminalErrorCode` に移動しました。機能を維持するために、import ステートメントと Terminal のエラーコードの定義を更新してください。 - 新しい Terminal のエラーコード `TerminalErrorCode.GENERIC_READER_ERROR` を追加しました。これは、SDK が古く、スマートリーダーから返されたエラーを認識できない場合に発生します。このエラーを解決するには、Terminal SDK を更新する必要があります。 - Android の Tap to Pay では、`Terminal::collectPaymentMethod` および `Terminal::collectSetupIntentPaymentMethod` が取引から 60 秒後にタイムアウトするようになりました。`TerminalException` がエラーコード `TerminalErrorCode.CARD_READ_TIMED_OUT` で発生します。 - Android のTap to Pay では、PIN の収集が決済のためにリクエストされると、`ONLINE_OR_OFFLINE_PIN_REQUIRED` `ApiError` が指定された `DECLINED_BY_STRIPE_API` ではなく、エラーコード `FEATURE_NOT_ENABLED_ON_ACCOUNT` の `TerminalException` が発生します。 ## 名称変更およびリファクタリングに関する更新 - `ReaderListener` の名前が [`MobileReaderListener`]](https://stripe.dev/stripe-terminal-android/external/com.stripe.stripeterminal.external.callable/-mobile-reader-listener/index.html) に変更されました。 - `PaymentIntentParameters.Builder` と `SetupIntentParameter.Builder` コンストラクターの `allowedPaymentMethodTypes` パラメーターの名前を `paymentMethodTypes` に変更しました。 - `ReaderSoftwareUpdate` で、`UpdateTimeEstimate` を `UpdateDurationEstimate` に、`estimatedUpdateTime` を `durationEstimate` に名前を変更しました。これにより、意図が把握しやすくなります。 - `ReaderSoftwareUpdate::requiredAt` フィールド、`OfflineDetails::storedAt` フィールド、`OfflineSetupIntentDetails::storedAt` フィールドの `java.util.Date` リファレンスをミリ秒単位のタイムスタンプに変換しました。アプリケーションがこれらのタイムスタンプを正しく解釈できているかご確認ください。 - `Location` オブジェクトのフィールドは変更できなくなりました。 ## Android の Tap to Pay 統合に関する更新 - Android の Tap to Pay 機能の Maven 座標が `com.stripe:stripeterminal-taptopay:4.0.0` に変更されました。ビルドの依存関係を更新して、新しいアーティファクト名を指定する必要があります。古いものは更新されなくなります。 - すべての `LocalMobile` の関数名とフィールド名を `TapToPay` に変更しました。たとえば、`LocalMobileDiscoveryConfiguration` は `TapToPayDiscoveryConfiguration` に名前が変更されています。 - `TapToPayConnectionConfiguration` が `TapToPayReaderListener` パラメーターを受け取るようになりました。このリスナーは `ReaderReconnectionListener` と `ReaderDisconnectionListener` の両方からイベントを引き継ぎ、リーダーイベントを処理するための統一メカニズムを提供します。 - Tap to Pay 取引の収集に使用されるバックグラウンドアプリケーションプロセスの名前を変更しました。アプリケーションの ID の末尾に `:stripetaptopay` が配置されるようになります。