リーダーに接続する

まず、リーダーの電源が入っていて、近くにあることを確認してください。

次に、アプリから BluetoothDiscoveryConfiguration を使用して、discoverReaders メソッドで近くにある Bluetooth 接続型リーダーを検索します。

class DiscoverReadersActivity : AppCompatActivity(), DiscoveryListener {

    var discoverCancelable: Cancelable? = null

    // ...

    // Action for a "Discover Readers" button
    fun discoverReadersAction() {
        val timeout = 0
        val isSimulated = false

        val config = BluetoothDiscoveryConfiguration(
            timeout = timeout,
            isSimulated = isSimulated
        )

        discoverCancelable = Terminal.getInstance().discoverReaders(
            config,
            this,
            object : Callback {
                override fun onSuccess() {
                    // Placeholder for handling successful operation
                }

                override fun onFailure(e: TerminalException) {
                    // Placeholder for handling exception
                }
            }
        )
    }

    // DiscoveryListener
    override fun onUpdateDiscoveredReaders(readers: List<Reader>) {
        // In your app, display the discovered readers to the user.
        // Call `connectReader` after the user selects a reader to connect to.
    }
}

Bluetooth スキャン

Bluetooth スキャンは、近くにあるすべてのリーダーを検索して、検出したリーダーのリストをアプリに返します。検出プロセスが続くと、SDK は近くのリーダーの最新リストを使用して onUpdateDiscoveredReaders メソッドを呼び出し続けます。

検出プロセスでは、検出中に Terminal の connectionStatus が ConnectionStatus.DISCOVERING に移行します。

Bluetooth スキャン検出方法では、一定時間でスキャンをタイムアウトするよう設定できます。これを使用して、バッテリーの残量を管理したり、デバイスが見つからないときにエラーメッセージを表示したりできます。

ユーザーが自身のリーダーを認識できるようにするため、自動更新される検出リーダーリストを、シリアル番号やラベルと一緒にモバイルアプリに表示することをお勧めします。

検出されたリーダーに接続するには、アプリから connectReader メソッドを呼び出します。

接続の際、場所にリーダーを登録する必要があります。このためには、接続時に locationId を関連する Location ID に設定し、BluetoothConnectionConfiguration を作成して使用します。

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

リーダーの連結の解除を処理する

リーダーの連結解除が、アプリとリーダーの間で発生することがあります。たとえば、リーダーが範囲外であるか、バッテリーが切れた場合、アプリからリーダーが連結解除されることがあります。リーダーの電源をオフにすると、テスト中に予期しない切断をシミュレーションできます。

MobileReaderListener には、onDisconnect コールバックが含まれています。これは、リーダーの接続が切断された理由を示す DisconnectReason をアプリケーションに提供します。

リーダーの接続が切断されると、デフォルトで自動再接続が試行されます。そのプロセスの間、リーダーのステータスを伝える通知をアプリに表示することをお勧めします。

自動再接続中にアプリに通知を表示するには、次の操作を行います。

1. MobileReaderListener にリーダーの再接続コールバックを実装します。
2. MobileReaderListener を BluetoothConnectionConfiguration に渡します。
3. onReaderReconnectStarted をアプリに送信する際、SDK はリーダーの接続が失われ、再接続が進行中であることを伝えるメッセージを表示します。
   • Cancelable オブジェクトを使用して、いつでも再接続の試行を停止できます。
4. onReaderReconnectSucceeded を送信して再接続が成功したことを示す際、SDK は接続が復元され、通常の動作を続行できることを通知するメッセージを表示します。
5. リーダーに接続できず、onReaderReconnectFailed と onDisconnect の両方を送信した場合、SDK は予期しない切断が発生したことを示すメッセージを表示します。

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
    }

    // ...
}

リーダーの切断にご自身で対処するには、次の手順を実行します。

1. 接続中は autoReconnectOnUnexpectedDisconnect を false に設定します。
2. 切断コールバックを処理して、リーダーが予期せず切断されたことをユーザーに通知するメッセージをアプリに表示し、リーダーの検出と接続を開始します。

class ReaderActivity : AppCompatActivity(), MobileReaderListener {
    // ...

    override fun onDisconnect(reason: DisconnectReason) {
        // Consider displaying a UI to notify the user and start rediscovering readers
    }

    // ...
}

接続されたリーダーを再起動する

Stripe リーダー M2 および BBPOS WisePad 3 は、24 時間使用すると自動的に再起動します。ただし、rebootReader API を使用すると、リーダーを強制的に再起動して、24 時間のタイマーをリセットできます。このアクションの後、リーダーは SDK から切断され、再起動されます。自動再接続を使用している場合、SDK はリーダーとの接続を復元しようとします。

Terminal.getInstance().rebootReader(
    object : Callback {
        override fun onSuccess() {
            // Reboot succeeded and the reader will disconnect.
            // If your app is using automatic reconnect the reconnect will begin.
        }

        override fun onFailure(e: TerminalException) {
            // Placeholder for handling exception
        }
    }
)

アプリケーションの開始時の自動再接続

Stripe Terminal は、アプリケーションの起動時にリーダーに自動的に再接続しません。代わりに、リーダー ID を保存し、起動時に既知のリーダーへの接続を行うことで、再接続フローを構築できます。

1. リーダーに正常に接続したら、シリアル番号を Shared Preferences API (Android) などの永続的なデータ格納場所に保存します。

1. アプリが起動したら、その永続的なデータ格納場所に保存されているシリアル番号を確認します。確認できた場合は、discoverReaders メソッドを呼び出して、アプリケーションがそのリーダーを再度見つけられるようにします。
2. 保存されたシリアル番号が検出されたリーダーのいずれかと一致する場合は、discoverReaders の呼び出しから返された一致するリーダーオブジェクトを使用して、そのリーダーへの接続を試してください。以前に接続したリーダーが見つからない場合は、検出プロセスを停止します。

検出および接続プロセス中に何らかの UI を表示して、自動再接続が実行されていることを示します。

アプリケーションは、モバイルリーダーを更新して以下を適用する必要があります。

• カードネットワークとカード発行会社の要件に対して最新の状態に保つための地域設定
• セキュリティ更新

必要な更新では、リーダーに接続するとインストールが開始されます。更新が完了するまでリーダーを使用できません。

必要な更新

リーダーで緊急の更新が利用可能になると、システムの MobileReaderListener が ReaderSoftwareUpdate と onStartInstallingUpdate を受信します。

ReaderSoftwareUpdate は、更新に関する重要情報 (更新の合計推定時間を示す durationEstimate など) を提供します。

インストールプロセスでは、更新がリーダーにインストールされる間、Terminal の connectionStatus が ConnectionStatus.CONNECTING に移行します。

アプリケーションからユーザーに更新をインストール中であることを伝え、また UI に進捗状況を表示する必要があります。接続に通常よりも時間がかかる理由を明確にします。

必須の更新のプロセスが失敗した場合、Stripe は onFinishInstallingUpdate を使用して MobileReaderListener にエラーを通知します。必須の更新に失敗した後は、以下の条件が満たされない限り、リーダーに再接続することはできません。

• リーダーは、過去 30 日間の場所に対応する最新のソフトウェアバージョンを実行します。
• Android SDK バージョンが 3.5.0 以降でです。

条件が満たされると、更新が未完了であっても接続プロセスは成功します。Stripe は、更新が正常にインストールされるまで、次回そのリーダーに接続したときに、必要な更新を再試行します。

class ReaderActivity : AppCompatActivity(), MobileReaderListener {
    // ...

    override fun onStartInstallingUpdate(update: ReaderSoftwareUpdate, cancelable: Cancelable) {
        // Show UI communicating that a required update has started installing
    }

    override fun onReportReaderSoftwareUpdateProgress(progress: Float) {
        // Update the progress of the installation
    }

    override fun onFinishInstallingUpdate(update: ReaderSoftwareUpdate?, e: TerminalException?) {
        // Report success or failure of the update
    }

    // ...
}

Cancelable オブジェクトを使用すると、必要な更新をキャンセルできますが、キャンセルした場合もリーダーに接続できなくなります。増分のみの更新はキャンセルできません。

オプションの更新

任意の更新は、指定した日付まで先延ばしすることが可能で、その後必須になります。リーダーの接続中、処理が行われていないときは SDK が随時 MobileReaderListener を通じて任意の更新を通知します。任意の更新が提供されている場合、アプリケーションの MobileReaderListener は、以下の更新情報を含む ReaderSoftwareUpdate オブジェクトとともに onReportAvailableUpdate コールバックを受信します。

• 更新にかかる推定時間 (durationEstimate)
• 更新が必要になる日付 (requiredAt)

アプリケーションで、更新が提供されていることをユーザーに伝え、必要に応じて更新に進むための画面を表示します。

onReportAvailableUpdate ですでに通知されている更新を続けるには、Terminal.getInstance().installAvailableUpdate をコールします。

利用可能な更新は、リーダーオブジェクトにも reader.availableUpdate として保存されます。

更新中は、顧客がアプリのページから移動できないようにするとともに、更新が完了するまでリーダーを受信範囲内に置き、電源を入れたままにしておくように指示します。また、更新の進捗状況を視覚的に示すインジケーターを、顧客に表示することもお勧めします。MobileReaderListener は、onReportReaderSoftwareUpdateProgress メソッドで更新の進捗状況を報告します。

オプションの更新の requiredAt の期日を過ぎると、次回リーダーが接続されたときに更新がインストールされます。

class ReaderActivity : AppCompatActivity(), MobileReaderListener {
    // ...

    override fun onReportAvailableUpdate(update: ReaderSoftwareUpdate) {
        // An update is available for the connected reader. Show this update in your application.
        // Install this update using `Terminal.getInstance().installAvailableUpdate`.
    }

    // ...
}

アプリケーションがリーダーに適用可能な各種の更新タイプを処理できるようにするには、リーダーの更新をテストする をご覧ください。