リーダーに接続する
注
まだリーダーを選択していない場合は、利用可能な Terminal リーダーを比較して、ニーズに最適なリーダーを選択してください。
Bluetooth 接続型リーダーは Bluetooth LE デバイスです。支払い詳細を収集しますが、Stripe との通信にはペアリングされたモバイルデバイスを使用します。
Bluetooth を使用してアプリを Terminal リーダーに接続するには、次のステップを実行します。
注意
リーダーとペアリングするために、モバイルデバイス設定を使用しないでください。デバイス設定を使用してリーダーをペアリングすると、リーダーをアプリに接続できなくなります。
リーダーを検出するクライアント側
まず、リーダーの電源を入れます。次に、discoverReaders メソッドを使用して、アプリケーションから近くにある Bluetooth 接続型リーダーを検索します。
Bluetooth 近接センサー * BBPOS Chipper 2X BT のみ
Bluetooth 近接センサーは、検索結果をフィルターして最も近いリーダーを返します。リーダーが検出されると、そのリーダーはマルチカラーで点滅するため、複数のリーダーの中でどのリーダーが検出されたのかがわかります。SDK がリーダーを検出した後は、その検出されたリーダーをオフにしない限り、より近くにあるリーダーに切り替わりません。
Bluetooth 近接センサーを使用すると、SDK はアプリのコールバックにリーダーを 2 回返します。最初に、アプリはリーダーのシリアル番号のみが入力された Reader
オブジェクトを受信します。その後少ししてから、リーダーのバッテリーレベルなどの新しい情報が入力された Reader
オブジェクトを受信します。
ユーザーがそのリーダーへの接続を確認したり、そのリーダーへの接続を希望しない場合にキャンセルしたりできるように、アプリの UI に検出されたリーダーを表示することをお勧めします。
Bluetooth スキャン
Bluetooth スキャンは、近くにあるすべてのリーダーを検索して、検出したリーダーのリストをアプリケーションに返します。検出プロセスが続くと、SDK は近くのリーダーの最新リストで、DiscoveryDelegate.didUpdateDiscoveredReaders
メソッドを呼び出し続けます。
Bluetooth スキャン検出方法では、一定時間のスキャンのタイムアウトを設定できます。これを使用して、バッテリーの残量を管理したり、デバイスが見つからないときにエラーメッセージを表示できます。
ユーザが自身のリーダーを認識できるようにするため、自動更新される検出リーダーリストを、シリアル番号やラベルと一緒にモバイルアプリケーションに表示することをお勧めします
リーダーに接続するクライアント側
検出されたリーダーに接続するには、アプリから connectBluetoothReader
メソッドを呼び出します。SDK がリーダーに接続すると、すぐにそのステータスライトが青く点灯します。
接続の際、場所にリーダーを登録する必要があります。このためには、接続時に locationId
を関連する Location ID に設定し、BluetoothConnectionConfiguration
を作成して使用します。
アプリをバックグラウンドで実行し、リーダーへの接続が保持された状態にするには、アプリを設定して、必要なバックグラウンドモードを追加します。
アプリで省エネを目的として disconnectReader
を呼び出すプログラムは使用しないでください。リーダーは、スタンバイモードを使用して効率的に電源を管理します。
リーダーの切断を処理する
リーダーの切断が、アプリとリーダーの間で発生することがあります。たとえば、リーダーは、範囲外に出たり、バッテリーが切れたりすると、アプリから切断されることがあります。リーダーの電源をオフにすると、テスト中に予期せぬ切断をシミュレーションできます。
BluetoothReaderDelegate
には reader:didDisconnect:
が含まれています。これは、リーダーの接続が切断された理由を特定できるように DisconnectReason
をアプリケーションに提供します。
次の 2 つの方法で切断に対処できます。
切断に即時に対処する
このオプションでは、リーダーが切断された場合に手動で対処できるようにするために、アプリで didReportUnexpectedReaderDisconnect
コールバックを実装する必要があります。これは SDK のデフォルトの動作です。
このコールバックの実装で、UI を表示してリーダーが切断されたことをユーザーに通知します。
リーダーは、範囲外に出たり、バッテリーが切れたりすると、アプリから切断されます。テスト中に想定外の接続の切断をシミュレーションするには、リーダーの電源をオフにします。
自動的に再接続を試行する
このオプションでは、アプリで BluetoothConnectionConfiguration
の autoReconnectOnUnexpectedDisconnect
を true として設定し、ReconnectionDelegate
で見つかったコールバックを実装する必要があります。また、autoReconnectionDelegate
を BluetoothConnectionConfiguration
に渡す必要もあります。
自動的に再接続を試行すると、以下が発生します。
- 切断が発生すると、SDK は自動的に再接続しようとし、
didStartReaderReconnect
を介して通知します。接続が切れて、再接続が進行中であることを必ずアプリで知らせてください。Cancelable
オブジェクトを使用して、いつでも再接続の試行を停止できます。
- SDK でリーダーへの再接続が成功すると、
didSucceedReaderReconnect
を介して通知されます。接続が復元され、通常の動作を続行できることを、必ずアプリで知らせてください。 - SDK がリーダーに接続できない場合は、
didFailReaderReconnect
を介して通知されます。必ず、予期しない切断が発生したことをアプリで知らせてください。
接続されたリーダーを再起動する
Stripe リーダー M2 および BBPOS WisePad 3 は、24 時間使用すると自動的に再起動します。ただし、rebootReader
API を使用すると、リーダーを強制的に再起動して、24 時間のタイマーをリセットできます。このアクションの後、リーダーは SDK から切断され、再起動されます。自動再接続を使用している場合、SDK はリーダーとの接続を復元しようとします。
アプリケーションの開始時の自動再接続
Stripe Terminal は、アプリケーションの起動時にリーダーに自動的に再接続しません。代わりに、リーダー ID を保存し、起動時に既知のリーダーへの接続を行うことで、再接続フローを構築できます。
- リーダーに正常に接続されたら、シリアル番号を UserDefaults API (iOS) などの永続的なデータ格納場所に保存します。
- アプリが起動したら、その永続的なデータ格納場所に保存されているシリアル番号を確認します。確認できた場合は、
discoverReaders
メソッドを呼び出して、アプリケーションがそのリーダーを再度見つけられるようにします。 - 保存されたシリアル番号が検出されたリーダーのいずれかと一致する場合は、
discoverReaders
の呼び出しから返された一致するリーダーオブジェクトを使用して、そのリーダーへの接続を試してください。以前に接続したリーダーが見つからない場合は、検出プロセスを停止します。
検出および接続プロセス中に何らかの UI を表示して、自動再接続が実行されていることを示します。
リーダーソフトウェアを更新するクライアント側
アプリケーションから Bluetooth リーダーを更新できるようにする「必要があります」。リーダーがリーダー自体を更新することはできません。更新には、カードネットワークとカード発行会社の要件を最新の状態に維持する地域設定のほか、セキュリティ更新が含まれることもあります。必要な更新がある場合、リーダーが接続されるとインストールが開始されます。インストールが完了するまでリーダーを使用することはできません。
注
更新をインストールするには、リーダーの充電率が 50% を超えている必要があります。
必要な更新
即時に必要な更新がリーダーで利用可能になると、システムの BluetoothReaderDelegate
は ReaderSoftwareUpdate
とともに didStartInstallingUpdate
コールバックを受信します。 ReaderSoftwareUpdate
は、estimatedUpdateTime
で示される更新の合計推定期間を含む、更新に必要な詳細を提供します。インストールプロセスでは、更新がリーダーにインストールされている間、Terminal の connectionStatus
が connecting
に移行します。
接続プロセスが通常よりも長くかかっている理由がはっきりとわかるように、アプリケーションからユーザーに更新をインストール中であることを伝え、また UI に進捗状況を表示する必要があります。
必要な更新プロセスが失敗した場合、Stripe は BluetoothReaderDelegate
にエラーを通知します。以下の条件が満たされない限り、接続は同じエラーで失敗します。
- リーダーは、過去 30 日間の場所に対応する最新のソフトウェアバージョンを実行します。
- iOS SDK バージョンが
3.5.0
以降です。
条件が満たされると、必要な更新が未完了でも接続プロセスは成功します。Stripe は、更新が正常にインストールされるまで、次回そのリーダーに接続したときに、必要な更新を再試行します。
Cancelable
オブジェクトを使用すると、必要な更新をキャンセルできます。ただし、キャンセルするとリーダーに接続できなくなります。増分のみの更新はキャンセルできないため、 Cancelable
は提供されません。
オプションの更新
オプションの更新は先延ばしにできますが、特定の日付までにインストールされない場合は、必要な更新になります。リーダーの接続中、処理が行われていないときに随時、オプションの更新が BluetoothReaderDelegate
に通知されます。オプションの更新が利用可能になると、アプリケーションの BluetoothReaderDelegate
は、更新の詳細を含む ReaderSoftwareUpdate
オブジェクトとともに didReportAvailableUpdate
コールバックを受信します。この更新は Reader オブジェクトにも reader.availableUpdate
として保存され、Terminal.installAvailableUpdate
を呼び出したときにインストールされる更新となります。Update オブジェクトには、更新にかかる推定時間 (estimatedUpdateTime
) と、更新をインストールしなければならない期限日 (requiredAt
) が含まれています。
アプリケーションで、更新が提供されていることをユーザーに伝え、必要に応じて更新に進むための画面を表示します。
更新を進めるには、installAvailableUpdate
を呼び出します。これにより、didReportAvailableUpdate
を介してすでに通知されている更新がインストールされます。
更新の進行中は、ユーザがアプリのページから移動できないようにするとともに、更新が完了するまでリーダーを受信範囲内に置き、電源を入れたままにしておくように指示します。さらに、更新の進捗状況を視覚的に示すインジケータをユーザに表示することもお勧めします。BluetoothReaderDelegate
は didReportReaderSoftwareUpdateProgress
メソッドを使用して更新の進捗状況を報告します。
オプションの更新の requiredAt
の期日を過ぎると、いったんリーダーの接続を解除して再接続が行われるまで、更新はインストールされなくなります。
アプリケーションがリーダーに適用可能な各種の更新タイプを処理できるようにするには、Bluetooth リーダーの更新をテストするをご覧ください。
BBPOS および Chipper™ の名称およびロゴは BBPOS Limited の米国および/またはその他の国における商標または登録商標です。Verifone® の名称およびロゴは Verifone の米国および/またはその他の国における商標または登録商標のいずれかです。これらの商標の使用は BBPOS または Verifone による何らかの承認を意味するものではありません。