リーダーに接続する
注
まだリーダーを選択していない場合は、利用可能な Terminal リーダーを比較して、ニーズに最適なリーダーを選択してください。
Stripe Reader M2、BBPOS WisePad 3、BBPOS Chipper 2X BT のリーダーで USB 接続をサポートするには、Stripe Terminal Android SDK 2.22.0 (以降) を使用します。USB 接続型リーダーでは、リーダーへの有線接続を使用することで、Bluetooth の干渉と切断の問題を回避できます。
Stripe Reader M2 や BBPOS WisePad 3 に付属の USB 2.0 ケーブルなど、データと充電の両方に対応する USB ケーブルを使用する必要があります。BBPOS Chipper 2X BT に付属のケーブルのように、Terminal リーダーに付属のケーブルが充電専用である場合は、データを送信できる他社の USB 2.0 ケーブルを使用してください。
USB ケーブルを使用してアプリを Terminal リーダーに接続するには、次のステップを実行します。
注意
リーダーとペアリングするために、モバイルデバイス設定を使用しないでください。デバイス設定を使用してリーダーをペアリングすると、リーダーをアプリに接続できなくなります。
リーダーを検出するクライアント側
discoverReaders メソッドを使用して、POS アプリで近くにあるリーダーを検索できるようにします。USB 接続型デバイスを検出するには、DiscoveryConfiguration.discoveryMethod
を USB に設定する必要があります。
リーダーの電源が入っていて、アプリを実行しているデバイスに USB 2.0 ケーブルで接続されていることを確認します。メッセージが表示されたら、USB 接続型リーダーへのアクセスの権限を付与します。
リーダーを初めて接続する場合、接続のための Android システムメッセージが表示されます。「常に開く」チェックボックスを選択して、リーダーの接続時にメッセージを表示せずにアプリが開くようにすることができます。
リーダーに接続するクライアント側
検出されたリーダーに接続するには、アプリから connectUsbReader
メソッドを呼び出します。SDK がリーダーに接続すると、すぐにリーダーのステータスライトが青く点灯します。
接続の際、場所にリーダーを登録する必要があります。このためには、接続時に locationId
を関連する Location ID に設定し、UsbConnectionConfiguration
を作成して使用します。
アプリで省エネを目的として disconnectReader
を呼び出すプログラムは使用しないでください。リーダーは、スタンバイモードを使用して効率的に電源を管理します。
接続タイプの優先順位を設定する
Terminal SDK は、特定の接続タイプを他の接続タイプよりも自動的に優先することはありません。検出するデバイスを USB または Bluetooth で切り替える機能が必要な場合は、この機能を POS アプリに実装することができます。discoverReaders
を呼び出し、DiscoveryConfiguration
で discoveryMethod
を設定します。
USB と Bluetooth で切り替えるには、他のタイプを開始する前に、現在の接続タイプに対して disconnectReader
を呼び出します。たとえば、Bluetooth 接続型リーダーに対して disconnectReader
を呼び出してから、connectUsbReader
を呼び出します。
リーダーの切断を処理する
リーダーの切断が、アプリとリーダーの間で発生することがあります。たとえば、リーダーをデバイスに接続する USB ケーブルがはずれた場合は、アプリからリーダーが切断されることがあります。リーダーの電源をオフにすると、テスト中に予期しない切断をシミュレーションできます。
ReaderListener
には、onDisconnect
コールバックが含まれています。これは、リーダーの接続が切断された理由を特定するために DisconnectReason
をアプリケーションに提供します。
次の 2 つの方法で切断に対処できます。
切断に即時に対処する
このオプションでは、リーダーが切断された場合に手動で対処できるようにするために、アプリで UnexpectedReaderDisconnect
コールバックを実装する必要があります。これは SDK のデフォルトの動作です。
このコールバックの実装で、UI を表示してリーダーが切断されたことをユーザーに通知します。
リーダーをデバイスに接続する USB ケーブルが外れた場合は、アプリからリーダーが切断されることがあります。テスト中に予期しない切断をシミュレーションするには、リーダーの電源をオフにします。
自動的に再接続を試行する
このオプションでは、アプリで UsbConnectionConfiguration
の autoReconnectOnUnexpectedDisconnect
を true に設定し、ReconnectionListener
で見つかったコールバックを実装する必要があります。また、autoReconnectionListener
を UsbConnectionConfiguration
に渡す必要もあります。
自動的に再接続を試行すると、以下が発生します。
- 切断が発生すると、SDK は自動的に再接続しようとし、
onReaderReconnectStarted
を介して通知します。接続が切れて、再接続が進行中であることを必ずアプリで知らせてください。
Cancelable
オブジェクトを使用して、いつでも再接続の試行を停止できます。
- SDK でリーダーへの再接続が成功すると、
onReaderReconnectSucceeded
を介して通知されます。接続が復元され、通常の動作が続行することを、必ずアプリで知らせてください。 - SDK がリーダーに接続できない場合は、
onReaderReconnectFailed
を介して通知されます。必ず、予期しない切断が発生したことをアプリで知らせてください。
接続されたリーダーを再起動する
Stripe リーダー M2 および BBPOS WisePad 3 は、24 時間使用すると自動的に再起動します。ただし、rebootReader
API を使用すると、リーダーを強制的に再起動して、24 時間のタイマーをリセットできます。このアクションの後、リーダーは SDK から切断され、再起動されます。自動再接続を使用している場合、SDK はリーダーとの接続を復元しようとします。
アプリケーションの開始時の自動再接続
Stripe Terminal は、アプリケーションの起動時にリーダーに自動的に再接続しません。代わりに、リーダー ID を保存し、起動時に既知のリーダーへの接続を行うことで、再接続フローを構築できます。
- リーダーに正常に接続したら、シリアル番号を Shared Preferences API などの永続的なデータ格納場所に保存します。
- アプリが起動したら、その永続的な格納場所に保存されているシリアル番号を確認します。確認できた場合は、
discoverReaders
メソッドを呼び出して、アプリケーションがそのリーダーを再度見つけられるようにします。 - 保存されたシリアル番号が検出されたリーダーのいずれかと一致する場合は、
discoverReaders
の呼び出しから返された一致するリーダーオブジェクトを使用して、そのリーダーへの接続を試してください。以前に接続したリーダーが見つからない場合は、検出プロセスを停止します。
検出および接続プロセス中に何らかの UI を表示して、自動再接続が実行されていることを示すことができます。
リーダーソフトウェアを更新するクライアント側
アプリケーションからリーダーを更新できるようにする「必要があります」。リーダーがリーダー自体を更新することはできません。更新には、カードネットワークとカード発行会社の要件を最新の状態に維持する地域設定のほか、セキュリティ更新が含まれることもあります。必要な更新のインストールは、リーダーが接続されると開始されます。インストールが完了するまでリーダーを使用することはできません。
注
更新をインストールするには、リーダーのバッテリーが 50% 以上充電されている必要があります。
必要な更新
リーダーに直ちに必要な更新がある場合、変更内容の送信中は Terminal の connectionStatus
が ConnectionStatus.CONNECTING
に変わります。必要な更新がリーダーにインストールされるまで、接続プロセスは完了しません。
更新には 30 秒以上かかると予測されますが、その間にアプリケーションの ReaderListener
は、更新の詳細が含まれる ReaderSoftwareUpdate
オブジェクトとともに onStartInstallingUpdate
を受信します。このオブジェクトには、更新の合計推定時間である timeEstimate
が含まれます。
接続プロセスが通常よりも長くかかっている理由がはっきり分かるように、アプリで更新をインストール中であることをユーザーに伝え、進捗状況を表示します。
Cancelable
オブジェクトを使用すると、必要な更新をキャンセルできます。ただし、キャンセルするとリーダーに接続できなくなります。増分のみの更新はキャンセルできないため、 Cancelable
は提供されません。
オプションの更新
リーダーの接続中、処理が行われていないときに随時、オプションの更新が ReaderListener
に通知されます。アプリの ReaderListener
は、更新の詳細を含む ReaderSoftwareUpdate
オブジェクトとともに onReportAvailableUpdate
コールバックを受信します。この更新は Reader オブジェクトにも reader.availableUpdate
として保存され、Terminal.installAvailableUpdate
を呼び出したときにインストールされます。Update オブジェクトには、更新にかかる推定時間 (timeEstimate
) と更新をインストールしなければならない期限日 (requiredAt
) が含まれています。
アプリでは、インストールできる更新をユーザーに通知し、必要に応じて更新を続行するためのメッセージを表示します。続行するには、installAvailableUpdate
を呼び出し、onReportAvailableUpdate
で更新をインストールします。
更新のインストール中は、ユーザーがアプリのページから移動できないようにするとともに、更新が完了するまでリーダーを接続して電源を入れたままにしておくように指示します。更新の進捗状況を視覚的に示すインジケーターをユーザーに表示することをお勧めします。ReaderListener
で onReportReaderSoftwareUpdateProgress
メソッドを使用できます。
requiredAt
の期日を過ぎると、リーダーの接続を解除して再接続が行われるまで、オプションの更新はインストールされません。
オプションの更新は先延ばしにできますが、特定の日付までにインストールされない場合は、必須の更新に変わります。
BBPOS および Chipper™ の名称およびロゴは BBPOS Limited の米国および/またはその他の国における商標または登録商標です。Verifone® の名称およびロゴは Verifone の米国および/またはその他の国における商標または登録商標のいずれかです。これらの商標の使用は BBPOS または Verifone による何らかの承認を意味するものではありません。