Terminal SDK V4 移行ガイド

アプリケーションで現在、4.0.0 より前のバージョンの Terminal iOS SDK を使用している場合は、アップグレードしてカード提示決済をグローバルに受け付けるには、いくつかの変更を行う必要があります。バージョン 3.9.1 から 4.0.0 への変更の詳細なリストについては、SDK 変更ログをご覧ください。

iOS 14 以降のミニマムサポートバージョンに関する更新

Stripe は、開発者サポート業務を効率化するために SDK のミニマムサポートバージョンを定期的に更新しています。

現行の Terminal iOS SDK バージョン 3.X は、引き続き iOS 13 以降で動作するデバイスをサポートします。

PaymentIntent 統合後のカードの保存に関する更新

対面での PaymentIntent が成功した後に決済手段を保存する場合、統合で以下の更新を行う必要があります。

• Terminal PaymentIntents を作成する際に、[setup_future_usage](https://stripe.dev/stripe-terminal-ios/docs/4.0.0/Classes/SCPPaymentIntent.html#/c:objc(cs) パラメーターを渡します。これにより、今後同じカードで決済を行うことを Stripe に通知します。

• また、allow_redisplay を always または limited にして SCPCollectConfiguration に渡す必要があります。顧客の保存したカードを今後すべての決済フローで表示する場合は always を、サブスクリプションのような最初に設定した用途でのみ使用する場合は limited を渡します。

  決済後に決済詳細を保存する方法をご紹介します。

SetupIntent 統合での決済を伴わないカードの保存に関する更新

SetupIntents と PaymentIntents、および対面取引とオンライン取引の間の統合パターンの一貫性を確保するため、SCPTerminal の collectSetupIntentPaymentMethod で、これまですべての SetupIntent 取引で必須だった customerConsentCollected パラメーターを削除し、allowRedisplay パラメーターに置き換えました。

請求なしで直接保存する方法をご紹介します。

discoverReaders の使用に関する更新

• リーダー検出の実行状況を示す新しい列挙値 discovering を SCPConnectionStatus に追加しました。統合でこの新しい状態に対応できることを確認し、関連する情報を顧客に伝達してください。

• 複数のリーダー同時検出操作の処理が改善されました。以前は、discoverReaders を複数回呼び出すと、操作がキューに保持されていました。既存の操作がすでに進行中であるときに新しい discoverReaders が呼び出されると、SDK は進行中の操作をキャンセルし、SCPErrorCanceledDueToIntegrationError エラーを返します。その後、新しい discoverReaders 操作が直ちに開始します。

• スマートリーダーおよび Tap to Pay リーダーを見つけると、操作の終了時に discoverReaders の完了ブロックが呼び出されるようになりました。この変更は、これらのリーダータイプに対するリーダー検出が長時間実行される操作ではないことを表しています。

• SDK で SCPDiscoveryDelegate への参照を強く保持していたバグを修正しました。アプリケーションが、検出イベントを受信するためにデリゲートへの参照を強く保持していることを確認してください。

リーダー接続の利用に関する更新

• リーダーの検出と接続で一貫した統合パターンが保たれるように、以前のリーダー接続メソッド (connectBluetoothReader、connectInternetReader、connectLocalMobileReader) をすべて connectReader に統合しました。正確な接続タイプは、渡された接続設定によって決定されます。

• モバイルリーダーと Tap to Pay リーダーでは、ReaderDelegate パラメーターが connectReader メソッドから削除され、代わりに以前 SCPReconnectionDelegate だった connectionConfig に移動しました。他のリーダータイプと同様に、スマートリーダーの InternetConnectionConfiguration も InternetReaderDelegate が渡されることを想定しています。これは、リーダーの切断などのイベントを統合に警告します。

導入前

// 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)")
    }
}

導入後

// Call `connectReader` 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(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)")
    }
}

詳細については、リーダーへの接続に関するドキュメントを参照してください。

モバイルリーダーと Tap to Pay リーダーで自動再接続がデフォルトで有効になりました

• モバイルリーダーと Tap to Pay リーダーを使用した Terminal 統合の耐障害性を高めるために、リーダーが予期せず切断された場合の 自動再接続がデフォルトで有効になっています。

• 再接続プロセスの間、ユーザーにリーダーの状態を知らせるために、アプリに通知を表示させることをお勧めします。SCPReconnectionDelegate は、リーダーの再接続メソッドを処理するために削除されました。その役割は、それぞれの ReaderDelegate に統合されています。再接続イベントを処理するには、モバイルリーダーの場合 MobileReaderDelegate を、Tap to Pay リーダーの場合 TapToPayReaderDelegate を使用します。

• 独自のリーダー再接続ロジックを実装していて、この動作を維持する必要がある場合は、[setAutoReconnectOnUnexpectedDisconnect](https://stripe.dev/stripe-terminal-ios/docs/Classes/SCPBluetoothConnectionConfigurationBuilder.html#/c:objc(cs) を false に設定することで、自動再接続を無効にできます。

導入前

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
    }
}

導入後

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
    }
}

詳細とコードスニペットについては、自動的に再接続を試行するを参照してください。

リーダー切断の処理に関する更新

• リーダーの切断時に通知を受け取るために、SCPTerminalDelegate から terminal:didReportUnexpectedReaderDisconnect: を削除して、すべてのリーダータイプの切断コールバックを統一しました。ReaderDelegates の一部として reader:didDisconnect: を使用すると、リーダーの切断時に通知が届きます。モバイルリーダーの場合、SCPDisconnectReason で切断の理由を確認できます。

自動再接続が有効になっている場合、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:) メソッドの両方が呼び出されます。

導入前

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
    }
}

導入後

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
    }
}

詳細については、手動で切断を処理するに関するドキュメントを参照してください。

決済の受け付け統合に関する更新

• 返された 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」に変更しました。