リーダーに接続する

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

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

リーダーはダッシュボードで直接追加できます。

登録コードで登録する

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
:

アカウントにリーダーを登録したら、InternetDiscoveryConfiguration を使用して、discoverReaders ですでに登録されているリーダーを検索し、POS アプリケーションに接続します。

前の手順でリーダーを登録した location を使用して、検索範囲を設定できます。

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 を使用して前回の呼び出しをキャンセルする必要があります。

InternetDiscoveryConfiguration は、オンラインでリーダーを検出するための timeout 値をオプションでサポートしています。これにより、オンラインでの試行が失敗した場合に、オフラインのリーダー検出にすばやくフォールバックできます。

POS アプリケーションをリーダーに接続するには、InternetConnectionConfiguration を使用して、選択したリーダーで connectReader を呼び出します。

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

複数の接続

リーダーに一度に接続できるのは、1 つの Stripe Terminal SDK インスタンスのみです。デフォルトでは、別のアプリケーションから connectReader を呼び出すと、SDK からリーダーへの既存の接続が受信した接続に置き換えられ、接続されていた SDK はリーダーから切断されます。connectReader メソッドでは、failIfInUse プロパティを含む設定オブジェクトを使用します。このプロパティのデフォルト値は false です。アプリケーションで failIfInUse を true に設定すると、connectReader コールに代替の動作が適用されます。そのため、別の SDK によって開始された collectPaymentMethod コールまたは confirmPaymentIntent コールをリーダーが処理している間は、受信する接続が失敗します。リーダーが別の SDK に接続されているにもかかわらず待機状態である場合 (collectPaymentMethod が呼び出される前にスプラッシュスクリーンが表示されます)、failIfInUse を設定しても接続の動作は変更されず、受信する接続リクエストにより、SDK からリーダーへの既存の接続は常に切断されます。

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

複数リーダーがある環境で接続の中断を最小限に抑えるため、アプリケーションを初めて接続する際に failIfInUse を true に設定することをお勧めします。次に、接続が最初に失敗した場合に failIfInUse を false に設定してユーザーが接続を再試行できるようにします。

このように設定すると、ユーザーの 1 人が使用中のリーダーに誤って接続しても、取引の処理が中断されることはありません。必要に応じて接続することもできます。

接続切断に対処する

リーダーの接続の切断に備え、アプリに reader(_, didDisconnect:) コールバックを実装します。このコールバックを実装する際は、リーダーの接続が切断されることを知らせる UI を表示するようにしてください。discoverReaders を呼び出してリーダーをスキャンすると、再接続が開始されます。

接続が切断されたリーダーへの再接続をアプリで自動的に試行したり、別のリーダーへの再接続を促す UI をユーザーに表示したりもできます。

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

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 を表示して、自動再接続が実行されていることを示します。