リーダーに接続する

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

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

モバイルアプリでは、ユーザーが自身のモバイルリーダーを特定しやすくするために、検出されたリーダーのシリアル番号を一覧表示し、自動更新されるようにすることをお勧めします。モバイルリーダーの検出時にはリーダーの label プロパティーには値が入りません。リーダーのわかりやすい名前を表示する場合は、アプリケーション側でシリアル番号とラベルの対応表を管理してください。

Bluetooth ペアリング

セキュリティを強化し、EU の規制に準拠するため、2025 年 11 月現在、Stripe は WisePad 3 クレジットカードリーダーに数値比較 Bluetooth ペアリングプロセスを使用しています。数値比較プロセスでは、ペアリング時にカードリーダーと POS デバイスの両方でパスキーを確認する必要があります。デバイスを最新のソフトウェアバージョンに更新したら、次の手順を実行して WisePad 3 を新しいモバイルアプリに接続します。POS デバイスが WisePad 3 リーダーを検出して表示したら、次の手順を実行します。

1. WisePad 3 と POS デバイスの両方で 6 桁のコードが一致していることを確認します。
2. WisePad 3 で 確定 を選択します。
3. POS デバイスで ペアリング を選択します。

検出されたリーダーに接続するには、アプリから 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. 接続中は 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
        }
    }
)

自動的に再接続を試行する

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

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

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
    }

    // ...
}

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

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

    // ...
}

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