リーダーに接続する

To start, make sure your reader is powered on and within close proximity.

Then from your app, search for nearby Bluetooth-connected readers with the discoverReaders method, using BluetoothScanDiscoveryConfiguration.

import StripeTerminal

class DiscoverReadersViewController: UIViewController, DiscoveryDelegate {

    var discoverCancelable: Cancelable?

    // ...

    // Action for a "Discover Readers" button
    func discoverReadersAction() throws {
        let config = try BluetoothScanDiscoveryConfigurationBuilder().build()
        self.discoverCancelable = Terminal.shared.discoverReaders(config, delegate: self) { error in
            if let error = error {
                print("discoverReaders failed: \(error)")
            } else {
                print("discoverReaders succeeded")
            }
        }
    }

    // ...

    // MARK: DiscoveryDelegate

    func terminal(_ terminal: Terminal, didUpdateDiscoveredReaders readers: [Reader]) {
        // In your app, display the discovered readers to the user.
        // Call `connectReader` after the user selects a reader to connect to.
    }
}

Bluetooth 近接センサー * BBPOS Chipper 2X BT のみ

Bluetooth 近接センサーは、検索結果をフィルターして最も近いリーダーを返します。リーダーが検出されると、そのリーダーはマルチカラーで点滅するため、複数のリーダーの中でどのリーダーが検出されたのかがわかります。SDK がリーダーを検出した後は、その検出されたリーダーをオフにしない限り、より近くにあるリーダーに切り替わりません。

Bluetooth 近接センサーを使用すると、SDK はアプリのコールバックにリーダーを 2 回返します。最初に、アプリはリーダーのシリアル番号のみが入力された Reader オブジェクトを受信します。その後少ししてから、リーダーのバッテリーレベルなどの新しい情報が入力された Reader オブジェクトを受信します。

ユーザーがそのリーダーへの接続を確認したり、そのリーダーへの接続を希望しない場合にキャンセルしたりできるように、アプリの UI に検出されたリーダーを表示することをお勧めします。

Bluetooth スキャン

Bluetooth scan searches for all nearby readers and returns a list of discovered readers to your app. As the discovery process continues, the SDK continues to invoke the DiscoveryDelegate.didUpdateDiscoveredReaders method with the latest list of nearby readers.

During the discovery process, the Terminal’s SCPConnectionStatus transitions to SCPConnectionStatus.SCPConnectionStatusDiscovering while the discovery is in progress.

With the Bluetooth scan discovery method, you can set a timeout to scan for a set period of time, which you can use for managing battery life or triggering an error message if no devices are found.

In your mobile application, we recommend displaying an auto-updating list of discovered readers, with serial numbers or labels to help users identify their reader.

To connect to a discovered reader, call the connectReader method from your app.

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

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

アプリをバックグラウンドで実行し、リーダーへの接続が保持された状態にするには、アプリを設定して、必要なバックグラウンドモードを追加します。

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

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

The MobileReaderDelegate includes a reader:didDisconnect: method that provides your application with the DisconnectReason to help identify why the reader disconnected.

When a reader disconnects, we automatically attempt reconnection by default and recommend that you display notifications in your app relaying the reader status throughout the process.

To display notifications in your app during automatic reconnection, do the following:

1. Implement the reader reconnect callbacks in the MobileReaderDelegate.
2. Pass the MobileReaderDelegate to your BluetoothConnectionConfiguration.
   ReaderViewController.swift

   Swift

   let connectionConfig: BluetoothConnectionConfiguration
   do {
       connectionConfig = BluetoothConnectionConfigurationBuilder(delegate: yourMobileReaderDelegate, locationId: presentLocationId)
           .build()
   } catch {
       // Handle error building the connection configuration
       return
   }
   
   Terminal.shared.connectReader(reader, connectionConfig: connectionConfig, completion: connectCompletion)

3. When the SDK sends reader:didStartReconnect:disconnectReason: to your app, display a message announcing that the reader lost connection and reconnection is in progress.
   • Cancelable オブジェクトを使用して、いつでも再接続の試行を停止できます。
4. When the SDK indicates successful reconnection by sending readerDidSucceedReconnect:, display a message announcing the connection was restored and to continue normal operations.
5. If the SDK can’t reconnect to the reader and sends both readerDidFailReconnect: and reader:didDisconnect:, display a message stating that an unexpected disconnect occurred.

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

To handle reader disconnects yourself, you can do the following:

1. Set autoReconnectOnUnexpectedDisconnect to false during connection.
2. Handle the disconnect callback to display a message in the app alerting the user that the reader unexpectedly disconnected and initiate reader discovery and connection.

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

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

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

Terminal.shared.rebootReader { error in
    if let error = error {
        // Placeholder for handling the error
    } else {
        // Reboot succeeded and the reader will disconnect.
        // If your app is using automatic reconnect the reconnect will begin.
    }
}

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

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

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

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

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

Your application must update mobile readers to apply the following:

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

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

必要な更新

When immediately required updates are available for the reader, the integration’s MobileReaderDelegate receives the didStartInstallingUpdate callback with a ReaderSoftwareUpdate.

The ReaderSoftwareUpdate provides the necessary details of the update, including an estimate of the total update duration, indicated by durationEstimate.

During the installation process, the Terminal’s connectionStatus transitions to connecting while the update installs on the reader.

Your application must notify users that an update is installing and display the progress in your UI. Make it clear why connecting might take longer than usual.

If the required update process fails, Stripe communicates the error to the MobileReaderDelegate with didFinishInstallingUpdate. You can’t reconnect to the reader after a required update fails, unless the following conditions are met:

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

If the conditions are met, the connection process succeeds despite an incomplete update. Stripe retries the required update the next time you connect to that reader until it’s successfully installed.

import UIKit
import StripeTerminal

class ReaderViewController: UIViewController, MobileReaderDelegate {

    // ...

    // MARK: MobileReaderDelegate

    func reader(_ reader: Reader, didStartInstallingUpdate update: ReaderSoftwareUpdate, cancelable: Cancelable?) {
        // Show UI communicating that a required update has started installing
    }

    func reader(_ reader: Reader, didReportReaderSoftwareUpdateProgress progress: Float) {
        // Update the progress of the installation
    }

    func reader(_ reader: Reader, didFinishInstallingUpdate update: ReaderSoftwareUpdate?, error: Error?) {
        // Report success or failure of the update
    }

    // ...
}

You can cancel required updates using the Cancelable object, which also results in a failed connection to the reader. You can’t cancel incremental-only updates.

オプションの更新

You can defer optional updates until the specified date, after which they become required. The SDK notifies you of optional updates through the MobileReaderDelegate any time the reader is connected but not performing a transaction. If an optional update is available, your application’s MobileReaderDelegate receives the didReportAvailableUpdate callback with the ReaderSoftwareUpdate object containing the update details, including:

• Estimated time for update to complete (durationEstimate)
• Timestamp after which the update becomes required (requiredAt)

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

To proceed with the update previously reported with didReportAvailableUpdate, call Terminal.shared.installAvailableUpdate.

The available update is also stored on the reader object as reader.availableUpdate.

As the update proceeds, block the user from leaving the page in your app, and instruct the user to keep the reader in range and powered on until the update completes. We recommend also providing your user with a visual indicator of the update’s progress. The MobileReaderDelegate reports the update’s progress in the didReportReaderSoftwareUpdateProgress method.

When an optional update’s requiredAt date has passed, the update installs the next time the reader is connected.

import UIKit
import StripeTerminal

class ReaderViewController: UIViewController, MobileReaderDelegate {

    // ...

    // MARK: MobileReaderDelegate

    func reader(_ reader: Reader, didReportAvailableUpdate update: ReaderSoftwareUpdate) {
        // An update is available for the connected reader. Show this update in your application.
        // Install this update using `Terminal.shared.installAvailableUpdate`.
    }

}

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