リーダーに接続する

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

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

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

登録コードで登録する

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
:

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

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

async function discoverReaders() {
  const config = {simulated: false, location: 
'{{LOCATION_ID}}'}
  const discoverResult = await terminal.discoverReaders(config);
  if (discoverResult.error) {
    console.log('Failed to discover: ', discoverResult.error);
  } else if (discoverResult.discoveredReaders.length === 0) {
    console.log('No available readers.');
  } else {
    // You should show the list of discoveredReaders to the
    // cashier here and let them select which to connect to (see below).
    connectReader(discoverResult);
  }
}

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

async function connectReader(discoverResult) {
  // Just select the first reader here.
  const selectedReader = discoverResult.discoveredReaders[0];

  const connectResult = await terminal.connectReader(selectedReader);
  if (connectResult.error) {
    console.log('Failed to connect:', connectResult.error);
  } else {
    console.log('Connected to reader:', connectResult.reader.label);
  }
}

複数の接続

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

const connectResult = await terminal.connectReader(reader, {fail_if_in_use: true});

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

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

接続切断に対処する

リーダーの接続が切れた場合に対処できるように、お客様のアプリに onUnexpectedReaderDisconnect コールバックを実装する必要があります。このコールバックを実装する場合は、リーダーの接続が切れたことをユーザーに知らせる UI を表示します。discoverReaders を呼び出してリーダーをスキャンし、再接続を開始できます。

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

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

const terminal = StripeTerminal.create({
  onFetchConnectionToken: fetchConnectionToken,
  onUnexpectedReaderDisconnect: unexpectedDisconnect,
});

function unexpectedDisconnect() {
  // Consider displaying a UI to notify the user and start rediscovering readers
}

自動再接続

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

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

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