実装方法を設定する

Stripe Terminal iOS SDK は、次のようなアプリと互換性があります。

• iOS 13 以上をサポートしている
• CocoaPods、Swift Package Manager を使用するか、手動でフレームワークを導入することによってインストールされている

アプリが Stripe Terminal SDK で動作するように準備するには、Xcode の Info.plist ファイルにいくつかの変更を加えます。

1. 次のキーと値のペアを使用して位置サービスを有効にします。

   プライバシー: Location When In Use Usage Description (使用されている位置の確認に関する記述)
   キー	NSLocationWhenInUseUsageDescription
   値	決済を受け付けるには、位置情報へのアクセスが必要です。

   決済に関連する不正使用のリスクを減らし、不審請求の申請を最小限に抑えるため、Stripe は決済が発生した場所を把握する必要があります。SDK が iOS デバイスの場所を特定できない場合は、位置情報へのアクセスが復元されるまで決済無効化されます。

2. アプリがバックグラウンドで実行され、Bluetooth リーダーに接続されたままであることを確認してください。

   Bluetooth リーダーに必要なバックグラウンドモード
   キー	UIBackgroundModes
   値	bluetooth-central (Bluetooth LE アクセサリーを使用)

   bluetooth-central バックグラウンドモードを設定すると、アプリがバックグラウンドで実行されている場合、または iOS デバイスがロックされている場合に、リーダーをスタンバイモードで保持することができます。この値がないと、スタンバイは失敗します。アプリがバックグラウンドで実行されている場合、リーダーは電力を節約するために自動的にオフになります。

3. アプリで Bluetooth に対する権限のダイアログを表示できるようにします。これは、アプリが Bluetooth リーダーへの接続に対応していない場合でも含める必要がある、アプリストアの必須要件です。

   プライバシー: Bluetooth Always Usage Description (Bluetooth の常時使用に関する記述)
   キー	NSBluetoothAlwaysUsageDescription
   値	このアプリは、Bluetooth を使用してサポート対象のカードリーダーに接続します。

   iOS 13 では、アプリによる Bluetooth 周辺機器の使用に関して、これまでよりも具体的な権限が新たに導入されました。Core Bluetooth とリンクするアプリは、初回起動時にアプリがクラッシュしないように、このキーを Info.plist ファイルに含める必要があります。

4. App Store に提出する際に、アプリの検証確認を渡します。SDK バージョン 3.4.0 では、この権限要件は削除されています。

   プライバシー: Bluetooth Peripheral Usage Description (Bluetooth 周辺機器の使用に関する記述)
   キー	NSBluetoothPeripheralUsageDescription
   値	サポート対象のカードリーダーに接続するには、Bluetooth 接続が必要です。

   これは一例です。アプリ内でのユーザーの権限を求めるプロンプトの文言を変更することもできます。

アプリの Info.plist を保存します。これで、正しく設定され、Stripe Terminal SDK で使用できるようになりました。

サーバー側

リーダーに接続するには、バックエンドからご自身の Stripe アカウントに、リーダーを使用するための SDK 権限を付与する必要があります。それには、ConnectionToken (接続トークン) から secret (シークレット) を提供します。バックエンドは信頼できるクライアントに対してのみ、接続トークンを作成するようにする必要があります。

curl https://api.stripe.com/v1/terminal/connection_tokens \
  -u 
sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  -X "POST"

Obtain the secret from the ConnectionToken on your server and pass it to the client side.

post '/connection_token' do
  token = # ... Create or retrieve the ConnectionToken
  {secret: token.secret}.to_json
end

クライアント側

To give the SDK access to this endpoint, implement the ConnectionTokenProvider protocol in your app, which defines a single function that requests a ConnectionToken from your backend.

import StripeTerminal

// Example API client class for communicating with your backend
class APIClient: ConnectionTokenProvider {

    // For simplicity, this example class is a singleton
    static let shared = APIClient()

    // Fetches a ConnectionToken from your backend
    func fetchConnectionToken(_ completion: @escaping ConnectionTokenCompletionBlock) {
        let config = URLSessionConfiguration.default
        let session = URLSession(configuration: config)
        guard let url = URL(string: "https://{{YOUR_BACKEND_URL}}/connection_token") else {
            fatalError("Invalid backend URL")
        }
        var request = URLRequest(url: url)
        request.httpMethod = "POST"
        let task = session.dataTask(with: request) { (data, response, error) in
            if let data = data {
                do {
                    // Warning: casting using `as? [String: String]` looks simpler, but isn't safe:
                    let json = try JSONSerialization.jsonObject(with: data, options: []) as? [String: Any]
                    if let secret = json?["secret"] as? String {
                        completion(secret, nil)
                    }
                    else {
                        let error = NSError(domain: "com.stripe-terminal-ios.example",
                                            code: 2000,
                                            userInfo: [NSLocalizedDescriptionKey: "Missing `secret` in ConnectionToken JSON response"])
                        completion(nil, error)
                    }
                }
                catch {
                    completion(nil, error)
                }
            }
            else {
                let error = NSError(domain: "com.stripe-terminal-ios.example",
                                    code: 1000,
                                    userInfo: [NSLocalizedDescriptionKey: "No data in response from ConnectionToken endpoint"])
                completion(nil, error)
            }
        }
        task.resume()
    }
}

この関数は、SDK で Stripe またはリーダーの認証が必要になるたびに呼び出されます。また、リーダーへの接続に新しい接続トークンが必要な場合 (アプリがリーダーから切断されたときなど) にも呼び出されます。SDK がバックエンドから新しい接続トークンを取得できない場合、リーダーへの接続は失敗し、サーバーからエラーが返されます。

The Terminal class made available by the Stripe Terminal SDK exposes a generic interface for discovering readers, connecting to a reader, and performing operations on the reader, such as displaying cart details, collecting payments, and saving cards for future use.

開始するには、ステップ 3 で実装された ConnectionTokenProvider を提供します。アプリで setTokenProvider を呼び出せるのは 1 回だけであり、Terminal.shared にアクセスする前に呼び出す必要があります。AppDelegate の application:didFinishLaunchingWithOptions メソッドで setTokenProvider を呼び出すことをお勧めします。また、Objective-C で dispatch_once を使用するか、Swift で static コンストラクターを使用することもできます。

import UIKit
import StripeTerminal

@UIApplicationMain
class AppDelegate: UIResponder, UIApplicationDelegate {

    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey : Any]? = nil) -> Bool {
        Terminal.setTokenProvider(APIClient.shared)
        // ...
        return true
    }

    // ...

}