リーダーに接続する

アプリケーションをスマートリーダーに接続するには、事前にリーダーをアカウントに登録しておく必要があります。

ダッシュボードで登録する

You can add your reader directly in the Dashboard.

登録コードで登録する

1. リーダーページで、リーダーを登録するをクリックします。
2. Verifone P400 をお持ちの場合は、0-7-1-3-9 の順にキーを入力すると、固有の登録コードが表示されます。BBPOS WisePOS E または Stripe リーダー S700 をお持ちの場合は、リーダー設定に移動し、ペアリングコードを生成をタップします。
3. 登録コードを入力して、次へをクリックします。
4. 任意でリーダーの名前を選択します。
5. すでに場所を作成している場合は、リーダーの新しい場所を選択します。まだ作成していない場合は、+ 新規追加をクリックして場所を作成します。
6. 登録するをクリックしてリーダーの登録を完了します。

シリアル番号で登録する

1. リーダーページで、リーダーを登録するをクリックします。
2. デバイスに記載されているシリアル番号を探し、そのシリアル番号を入力します。複数のデバイスを一度に登録するには、複数のシリアル番号をカンマで区切って入力します。
3. 任意でリーダーの名前を選択します。
4. すでに場所を作成している場合は、リーダーの新しい場所を選択します。まだ作成していない場合は、+ 新規追加をクリックして場所を作成します。
5. 登録するをクリックしてリーダーの登録を完了します。

ハードウェアの注文で登録する

1. ハードウェアの注文ページで、ステータスが「配送済み」または「配達済み」の注文を見つけます。行の最後にあるオーバーフローメニュー () をクリックし、次に登録するをクリックします。
2. リーダーを登録するページで、ハードウェアの注文から登録するリーダーを 1 つ以上選択して、登録するをクリックします。
3. 任意でリーダーの名前を選択します。複数のリーダーを選択した場合、名前はプレフィックスとして機能し、Stripe はリーダーに順番に名前を付けます (たとえば、「テストリーダー」と入力した場合、リーダーには「テストリーダー 1」、「テストリーダー 2」のように名前が付けられます)。
4. すでに場所を作成している場合は、リーダーの新しい場所を選択します。まだ作成していない場合は、+ 新規追加をクリックして場所を作成します。
5. 登録するをクリックしてリーダーの登録を完了します。

API を使用して登録する

大規模なデプロイでは、現場のユーザーがそれぞれ新しいリーダーを受け取って設定できるようにします。アプリで、Stripe API を使用してリーダーを登録するフローを構築します。

1. Verifone P400 をお持ちの場合は、0-7-1-3-9 の順にキーを入力すると、固有の登録コードが表示されます。BBPOS WisePOS E または Stripe リーダー S700 をお持ちの場合は、リーダー設定に移動し、ペアリングコードを生成をタップします。
2. ユーザーはアプリケーションにそのコードを入力します。
3. アプリケーションはそのコードを Stripe に送信します。

curl https://api.stripe.com/v1/terminal/readers \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d registration_code={{READER_REGISTRATION_CODE}} \
  --data-urlencode label="Alice's reader" \
  -d location=
{{LOCATION_ID}}

リーダーが正しく登録されたことを確認するには、その場所で登録したリーダーをすべて一覧表示します。

curl https://api.stripe.com/v1/terminal/readers \
  -u 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:

After registering the reader to your account, search for previously registered readers to connect to your point of sale application with discoverReaders, using InternetDiscoveryConfiguration.

You can scope your discovery using the location you registered the reader to in the previous step.

import StripeTerminal

class DiscoverReadersViewController: UIViewController, DiscoveryDelegate {
  func discoverReadersAction() throws {
      let config = try InternetDiscoveryConfigurationBuilder()
                          .setLocationId(
"{{LOCATION_ID}}")
                          .build()
      self.discoverCancelable = Terminal.shared.discoverReaders(config, delegate: self) { error in
          if let error = error {
              print("discoverReaders failed: \(error)")
          } else {
              print("discoverReaders succeeded")
          }
      }
  }
}

スマートリーダーを検索するときは discoverReaders を呼び出すたびに 1 回のみ DiscoveryDelegate.didUpdateDiscoveredReaders メソッドが呼び出されます。登録されたリーダーがない場合、または指定の場所に関連付けられたリーダーがない場合、didUpdateDiscoveredReaders はリーダーの空白のリストを返します。その後、discoverReaders を呼び出してリストを更新する場合は、まず discoverReaders によって返される Cancelable を使用して前回の呼び出しをキャンセルする必要があります。

The InternetDiscoveryConfiguration supports an optional timeout value for discovering readers online. This ensures quicker fallback to offline reader discovery if the online attempt fails.

To connect your point of sale application to a reader, call connectReader with the selected reader, using the InternetConnectionConfiguration.

let config: InternetConnectionConfiguration
do {
    config = try InternetConnectionConfigurationBuilder(delegate: yourInternetReaderDelegate)
        .build()
} catch {
    // Handle error building the connection configuration
    return
}

Terminal.shared.connectReader(selectedReader, connectionConfig: config) { reader, error in
    if let reader = reader {
        print("Successfully connected to reader: \(reader)")
    } else if let error = error {
        print("connectReader failed: \(error)")
    }
}

Multiple connections

Only one instance of the Stripe Terminal SDK can connect to a reader at a given time. By default, when you call connectReader from another application, the incoming connection replaces the existing SDK-to-reader connection, and the previously connected SDK disconnects from the reader. The connectReader method takes a configuration object with a failIfInUse property, whose default value is false. When your application sets failIfInUse to true, the connectReader call has an alternate behavior where the incoming connection fails when the reader is in the middle of a collectPaymentMethod or confirmPaymentIntent call initiated by another SDK. If the reader is connected to another SDK but is idle (displaying the splash screen before collectPaymentMethod is called), setting failIfInUse has no change to the connection behavior, and the incoming connection request can always break the existing SDK-to-reader connection.

let internetReaderDelegate = yourInternetReaderDelegate // implement your internetReaderDelegate

let config: InternetConnectionConfiguration
do {
    config = try InternetConnectionConfigurationBuilder(delegate: internetReaderDelegate)
          .setFailIfInUse(true)
          .build()
} catch {
    // Handle error building the connection configuration
    return
}
Terminal.shared.connectReader(selectedReader, connectionConfig: config, completion: { reader, error in
    // ...
})

For the least-disruptive connection experience in multi-reader environments, we recommend setting failIfInUse to true on your application’s initial connection attempt. Then, allow your users to retry the connection with failIfInUse set to false if the connection fails the first time.

With this setup, one of your users can’t accidentally interrupt a transaction by inadvertently connecting to an in-use reader, but can still connect if needed.

接続切断に対処する

Your app must implement the reader(_, didDisconnect:) callback to handle when a reader disconnects. When you implement this callback, display a UI that notifies your user of the disconnected reader. You can call discoverReaders to scan for readers and initiate reconnection.

Your app can attempt to automatically reconnect to the disconnected reader or display a UI that prompts your user to reconnect to a different reader.

リーダーでは、ネットワークへの接続が失われるとアプリとの接続が切断されることがあります。想定外の接続の切断をシミュレーションするには、リーダーの電源をオフにします。

import StripeTerminal

class ReaderViewController: UIViewController, InternetReaderDelegate {
    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 Terminal は、アプリケーションの起動時にリーダーに自動的に再接続しません。代わりに、リーダー ID を保存し、起動時に既知のリーダーへの接続を行うことで、再接続フローを構築できます。

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

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