# Terminal SDK V3 移行ガイド Stripe Terminal SDK (3.0.0) への移行方法を解説します。 Stripe Terminal iOS SDK および Android SDK が更新され、API と動作への重要な変更がいくつか行われました。その一部については Stripe Terminal SDK のシステムアップグレードが必要になります。Stripe は、SDK 間の一貫性を向上させ、アプリケーションロジックとシステムを効率化するために、定期的にメジャーバージョンの更新を行い、システムの機能や動作に影響を与える変更を加えています。このガイドでは、システムのアップグレードに関わる最新の変更について解説します。 > 新しい Stripe Terminal の導入を構築する場合は、[導入を設計する](https://docs.stripe.com/terminal/designing-integration.md)ページをご参照ください。 ## バージョン 3.0.0 に移行する Stripe Terminal iOS および Android の SDK 3.0.0 に関する変更点をいくつかご紹介します。 - オフライン決済の処理に対応する - オフラインモードの機能はプライベートプレビューです。ご利用をリクエストするには、[stripe-terminal-betas@stripe.com](mailto:stripe-terminal-betas@stripe.com](mailto:stripe-terminal-betas@stripe.com) にメールでご連絡ください。アカウントのバックエンドでの変更が有効にされた後で、SDK を使用してリーダーへの接続を切断してから再接続し、更新後の設定を反映する必要があります。 - iOS と Android でサポートされる最小プラットフォームバージョンの更新 - 非推奨の機能とプロパティの削除 # iOS > This is a iOS for when terminal-sdk-platform is ios. View the full page at https://docs.stripe.com/terminal/references/sdk-v3-migration-guide?terminal-sdk-platform=ios. アプリケーションが 3.0.0 より前のバージョンの Terminal iOS SDK を使用している場合、アップグレードしてカードの対面支払いをグローバルに受け付けるために、いくつかの変更が必要です。バージョン 2.23.1 から 3.0.0 への変更点の詳細なリストについては、[SDK 変更ログ](https://github.com/stripe/stripe-terminal-ios/releases/tag/v3.0.0)をご覧ください。 ## サポートされる最小バージョンを iOS 13 以降に更新 Stripe は、開発者に最適な体験を提供することに重点を置いており、SDK の最小サポートバージョンを定期的に更新しています。 Terminal iOS SDK の既存の 2.X バージョンでは、引き続き **iOS 11** 以降を実行するデバイスをサポートします。 ## DiscoveryConfiguration の使用方法を特定の DiscoveryConfiguration の実装向けに更新 さまざまな検出方法の設定をサポートするために、[SCPDiscoveryConfiguration](https://stripe.dev/stripe-terminal-ios/docs/Protocols/SCPDiscoveryConfiguration.html) は、複数のタイプで実装されるプロトコルになりました。DiscoveryMethod を提供する代わりに、特定のタイプのリーダーを検索するためのクラスから個別に選択できるようになっています。 | Configuration クラス | 使用状況 | | --------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- | | [SCPBluetoothScanDiscoveryConfiguration](https://stripe.dev/stripe-terminal-ios/docs/Classes/SCPBluetoothScanDiscoveryConfiguration.html) | この iOS デバイスの近くにある Bluetooth 対応リーダー | | [SCPBluetoothProximityDiscoveryConfiguration](https://stripe.dev/stripe-terminal-ios/docs/Classes/SCPBluetoothProximityDiscoveryConfiguration.html) | この iOS デバイスの近くにある Bluetooth 対応リーダーのサブセット | | [SCPInternetDiscoveryConfiguration](https://stripe.dev/stripe-terminal-ios/docs/Classes/SCPInternetDiscoveryConfiguration.html) | このアカウントに登録されたインターネット接続型リーダー | | [SCPLocalMobileDiscoveryConfiguration](https://stripe.dev/stripe-terminal-ios/docs/Classes/SCPLocalMobileDiscoveryConfiguration.html) | この iOS デバイスの NFC リーダーを使用する[タッチ決済](https://docs.stripe.com/terminal/payments/setup-reader/tap-to-pay.md?platform=ios) | 提供されたビルダークラスを使用して、目的の検出方法に適した検出設定を作成し、それを `discoverReaders` に提供してください。ビルダーは、それぞれの設定でサポートされるプロパティのセッターを表示します。 ## discoverReaders と connectReader の使用方法の更新 - `discoverReaders` を呼び出すと、その他すべてのキャンセル方法と同様に、コード `SCPErrorCanceled` のエラーで完了ブロックが呼び出されるようになりました。 - `connectReader` が呼び出されると `discoverReaders` がすぐに正しく完了するようになりました。`connectReader` が失敗した場合にリーダーの検出を再開するには、システムで `discoverReaders` を新たに呼び出す必要があります。 - `connectReader` を機能させるために、`discoverReaders` を実行する必要はなくなりました。以前検出されたリーダーインスタンスを使用して `connectReader` を呼び出すことも、`discoverReaders` を再開することなく接続を再試行することもできます。 ## ReconnectionDelegate の実装を更新 `SCPReconnectionDelegate` は Terminal インスタンスの代わりに再接続されているリーダーのインスタンスを提供するようになりました。このデリゲートを以前実装している場合、メソッド名の `terminal` を `reader` に置き換える必要があります。 ## ビルダーを使用するための、パラメーターと Configuration クラスの使用方法の更新 `SCPCollectConfiguration` や `SCPPaymentIntentParameters` などの入力クラスが変更不可能になり、それらを作成する関連ビルダーが含まれるようになりました。すべてのビルダーには、入力を検証し、構築するクラスを作成するビルドメソッドが含まれます。 - Swift では、`build()` がスローされ、エラーを確認する必要があります。 - Objective-C では、`NSError **` out パラメーターを指定して、該当する場合にエラーを受け取ります。 ```swift let paymentParams = try PaymentIntentParametersBuilder(amount: 100, currency: "cad") .setCaptureMethod(.automatic) .build() ``` ## SCPErrorBusy への依存を削除する `SCPErrorBusy` は削除されました。SDK 3.0.0 以降では、別のメソッドがまだ進行中の間に Terminal メソッドを呼び出すと、新しい呼び出しがキューに追加されるようになりました。コマンドは、前のコマンドがすべて完了した後で実行されます。以前 `SCPErrorBusy` を防ぐために状態を追跡していた場合、または `SCPErrorBusy` を解消するために自分で作成したコマンドをキューに追加していた場合は、コマンドキューを使用してコードをシンプルにできます。アプリケーションで `SCPErrorBusy` を使用してコマンドが実行中であるかを把握していた場合は、コードを参照し、キューに入れるコマンドが多くなりすぎて問題が発生していなかったかを確認してください。 ## オフライン決済のサポートを確認する オフライン決済では `SCPPaymentIntent.stripeId` は null になります。構築済みのシステムがオンライン決済のみに対応している場合、`stripeId` は常に表示されるため、ID が存在していることの確認以外に必要な変更はありません。オフライン時に支払いを処理する方法について、詳細は[オフラインでカード支払いを回収する](https://docs.stripe.com/terminal/features/operate-offline/collect-card-payments.md?terminal-sdk-platform=ios)をご覧ください。 ```swift Terminal.shared.createPaymentIntent(params) { intent, error in if let error = error { // Placeholder for handling exception } guard let intentId = intent.stripeId else { // PaymentIntent was created offline without an id. See intent.offlineDetails. // This is only expected when offline mode is enabled. } } ``` ## プロセス呼び出しを更新して確定する `SCPTerminal.processPayment` は `SCPTerminal.confirmPaymentIntent` に名前が変わり、`SCPTerminal.processRefund` は `SCPTerminal.confirmRefund` に名前が変わりました。これらのメソッドのパラメーターに変更はありませんが、エラータイプはそれぞれ `SCPConfirmPaymentIntentError` と `SCPConfirmRefundError` に変更されています。 ## readReusableCard の使用を SetupIntents の使用に更新 `SCPTerminal.readReusableCard` は削除されました。SetupIntents は、請求なしで決済手段を保存するための推奨手段です。SetupIntents は PaymentIntents と同様、SDK で作成、収集、確定されます。詳しくは、[オンライン決済で再利用するために支払い情報を保存する](https://docs.stripe.com/terminal/features/saving-payment-details/overview.md)を参照してください。 # Android > This is a Android for when terminal-sdk-platform is android. View the full page at https://docs.stripe.com/terminal/references/sdk-v3-migration-guide?terminal-sdk-platform=android. アプリケーションが 3.0.0 より前のバージョンの Terminal Android SDK を使用している場合、更新してカードの対面支払いをグローバルに受け付けるために、いくつかの変更が必要です。バージョン 2.23.1 から 3.0.0 への変更点のリストについては、[SDK 変更ログ](https://github.com/stripe/stripe-terminal-android/blob/master/CHANGELOG.md)をご覧ください。 ## サポートされる最小バージョンを Android 8 以降に更新 今後の Terminal Android SDK のバージョンでは、 **Android 8.0「Oreo」(API 26)** 以降を実行するデバイスのみがサポートされる予定です。Stripe では、開発者に最適な体験を提供することを重視するために、SDK の最小サポートバージョンを定期的に更新しています。SDK でサポートされる最小 API レベルを引き下げるために `minSdkVersion` を上書きしようとすると、内部の実行時 API レベルの検証によってブロックされます。 Terminal Android SDK の既存の 2.X バージョンでは、引き続き **Android 5.0「Lollipop」(API 21)** 以降を実行するデバイスをサポートします。 ## DiscoveryConfiguration の使用方法の更新 さまざまな検出方法の設定をサポートするために、[DiscoveryConfiguration](https://stripe.dev/stripe-terminal-android/external/com.stripe.stripeterminal.external.models/-discovery-configuration/index.html) クラスは、複数の sealed サブクラスによって実装されるインターフェイスになりました。DiscoveryMethod を提供する代わりに、特定のタイプのリーダーを検索するためのクラスから個別に選択できるようになっています。 | Configuration クラス | 使用状況 | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------- | | [BluetoothDiscoveryConfiguration](https://stripe.dev/stripe-terminal-android/external/com.stripe.stripeterminal.external.models/-discovery-configuration/-bluetooth-discovery-configuration/index.html) | この Android デバイスの近くにある Bluetooth 対応リーダー | | [UsbDiscoveryConfiguration](https://stripe.dev/stripe-terminal-android/external/com.stripe.stripeterminal.external.models/-discovery-configuration/-usb-discovery-configuration/index.html) | この Android デバイスが接続するリーダー | | [InternetDiscoveryConfiguration](https://stripe.dev/stripe-terminal-android/external/com.stripe.stripeterminal.external.models/-discovery-configuration/-internet-discovery-configuration/index.html) | このアカウントに登録されたインターネット接続型リーダー | | [LocalMobileDiscoveryConfiguration](https://stripe.dev/stripe-terminal-android/external/com.stripe.stripeterminal.external.models/-discovery-configuration/-local-mobile-discovery-configuration/index.html) | この Android デバイスの NFC リーダーを使用する[タッチ決済](https://docs.stripe.com/terminal/payments/setup-reader/tap-to-pay.md?platform=android) | | [HandoffDiscoveryConfiguration](https://stripe.dev/stripe-terminal-android/external/com.stripe.stripeterminal.external.models/-discovery-configuration/-handoff-discovery-configuration/index.html) | Stripe SmartPOS Android デバイスの [Apps on Devices](https://docs.stripe.com/terminal/features/apps-on-devices/overview.md) | ## 実行時権限のリクエストを実行するためのリーダーの検出の更新 これまでは、SDK の初期化時点で `Terminal.initTerminal()` の呼び出し時に、Location および Bluetooth の権限をアプリケーションに付与することが求められていました。これは厳しすぎる設定で、Bluetooth リーダーに接続していない実装にも、SDK を使用するために Bluetooth 権限の付与を求めることがよくありました。この要件が緩和され、リーダーの検出時に権限が確認され、`DiscoveryConfiguration` に基づいて最低限の権限セットのみが強制されるようになりました。 位置情報のアクセス許可は引き続き常に必要ですが、これらのアクセス許可が付与されているかどうかの確認は、`DiscoveryConfiguration` リーダーが検出されるまで延期されるようになりました。Bluetooth の利用許可もリーダーの検出時に確認されるようになりましたが、`BluetoothDiscoveryConfiguration` を持つリーダーを検索する場合にのみ確認を求められます。 ## 必要な更新のインストール時にリーダーの接続ステータスの変化を確認する 更新が必要なリーダーに Bluetooth または USB で接続しようとする場合、接続を正常に完了するには、その更新を適用する必要があります。以前までは、接続が確立されるとすぐにシステムの `TerminalListener.onConnectionStatusChange()` コールバックが `CONNECTED` で呼び出され、`TerminalListener.onPaymentStatusChanged()` は `READY` で呼び出されていました。ただし、リーダーに実行する必要のある更新がある場合は、これらのコールバックの受信中に更新がインストールされ、完了するまでリーダーのコマンドの受け付けが遅延します。 必要な更新をインストールする間、リーダーのステータスは `CONNECTING` のままになります。必要な更新が正常に完了した後にのみ、リーダーが接続され、利用できるようになったことが実装に通知されます。 ## オフライン決済のサポートを確認する オフライン決済では `PaymentIntent.id` は null になります。構築済みのシステムがオンライン決済のみに対応している場合、`id` は常に表示されるため、ID が存在していることの確認以外に必要な変更はありません。オフライン時に支払いを処理する方法について、詳細は[オフラインでカード支払いを回収する](https://docs.stripe.com/terminal/features/operate-offline/collect-card-payments.md?terminal-sdk-platform=android)をご覧ください。 ```kotlin Terminal.getInstance().createPaymentIntent( params, object : PaymentIntentCallback { override fun onSuccess(paymentIntent: PaymentIntent) { val intentId = paymentIntent.id ?: run { // PaymentIntent was created offline without an id. See intent.offlineDetails. // This is only expected when offline mode is enabled. } } override fun onFailure(e: TerminalException) { // Placeholder for handling exception } } ) ``` ## プロセス呼び出しを更新して確定する `Terminal.processPayment()` は `Terminal.confirmPaymentIntent()` に、`Terminal.processRefund()` は `Terminal.confirmRefund()` に名前が変わりました。メソッド名が変わったのみで、これらのメソッドの動作は同じです。 ## 細分化できるデータモデルの使用法を、シリアライズ可能なメソッドの使用に更新する 実装が Terminal SDK データモデルから Parcel への読み書きを必要とする場合、`writeParcelable()` と `readParcelable()` の呼び出しを、`writeSerializable()` と `readSerializable()` の呼び出しに更新する必要があります。 `Parcelable` データモデルでは、`Serializable` データを永続的なストレージに配置しないことが推奨されています。SDK の更新と更新の間に、`Serializable` データモデルのいずれかのデータの元になる実装が変更されると (新しいフィールドの追加など)、以前のデータが読めない状態でレンダリングされることがあります。 ## readReusableCard の使用を SetupIntents の使用に更新 `Terminal.readReusableCard()` は削除されました。SetupIntents は、請求なしで支払い情報を保存するための推奨手段です。SetupIntents は PaymentIntents と同様、SDK で作成、収集、確定されます。詳しくは、[オンライン決済で支払い情報を保存する](https://docs.stripe.com/terminal/features/saving-payment-details/overview.md)を参照してください。 ## 名前が変更または削除された非推奨の API の更新 非推奨になった多くのクラス、フィールド、メソッドが SDK から削除されました。削除されたほとんどの API には、代わりに読み込まれる代替フィールドがすでに用意されています。 - `CaptureMethod.getManual()` は削除されています。代わりに、`CaptureMethod.MANUAL` を使用してください。 - `CollectConfiguration` コンストラクターは削除されています。代わりに、`CollectConfiguration.Builder` を使用してください。 - `CollectConfiguration.moto` は変更可能ではなくなりました。 - `ConnectConfiguration.registerToLocation` が削除され、`ConnectConfiguration.locationId` に置き換わりました。 - `HandoffConnectionConfiguration` コンストラクターから `locationId` パラメーターが削除されました。 - `BluetoothReaderListener` と `UsbReaderListener` が削除され、`ReaderListener` に置き換わりました。 - `EmvBlob` が内部クラスとしてマークされました。 - `Reader.device` は削除され、`Reader.bluetoothDevice` および `Reader.usbDevice` に置き換わりました。 - `Reader.registeredLocation` は削除され、`Reader.location` に置き換わりました。 - `TerminalApplicationDelegate.onTrimMemory()` は削除されました。SDK によって自動的に管理されます。 - `CardDetails.fingerprint` と `CardPresentDetails.fingerprint` は削除されました。引き続き Stripe の [server-side SDKs](https://docs.stripe.com/sdks.md#server-side-libraries) を使用してフィンガープリントにアクセスできます。