Integration einrichten

Das Stripe Terminal iOS SDK ist mit Apps kompatibel, die:

• iOS 13 und höher unterstützen
• MIt CocoaPods, Swift Package Manager oder durch die manuelle Integration des Frameworks installiert werden

Damit Ihre App mit dem Stripe Terminal SDK verwendet werden kann, müssen Sie in Xcode einige Änderungen an Ihrer Datei Info.plist vornehmen.

1. Aktivieren Sie Standortdienste mit dem folgenden Schlüssel-Wert-Paar.

   Datenschutz – „Location When In Use Usage Description“
   Schlüssel	NSLocationWhenInUseUsageDescription
   Wert	Zur Annahme von Zahlungen ist ein Standortzugriff erforderlich.

   Um das Risiko von Betrugsfällen bei Zahlungen zu reduzieren und Zahlungsanfechtungen zu minimieren, muss Stripe den Standort der getätigten Zahlungen kennen. Wenn das SDK den Standort des iOS-Geräts nicht ermitteln kann, werden alle Zahlungen bis zur Wiederherstellung des Standortzugriffs deaktiviert.

2. Stellen Sie sicher, dass Ihre App im Hintergrund ausgeführt wird und mit den Bluetooth-Lesegeräten verbunden bleibt.

   Erforderliche Hintergrundmodi für Bluetooth-Lesegeräte
   Schlüssel	UIBackgroundModes
   Wert	bluetooth-central (Verwendet Zubehör von Bluetooth LE)

   Mit dem Festlegen des Hintergrundmodus bluetooth-central kann das Lesegerät im Standby-Modus bleiben, wenn die App im Hintergrund läuft oder wenn das iOS-Gerät gesperrt ist. Wird dieser Wert nicht angegeben, wird der Standby-Modus nicht aktiviert. Wenn Ihre App im Hintergrund läuft, kann sich das Lesegerät zum Energiesparen automatisch ausschalten.

3. Gestatten Sie Ihrer App, ein Dialogfeld für Bluetooth-Berechtigungen anzuzeigen. Der App-Store verlangt dies, auch wenn Ihre App die Verbindung mit Bluetooth-Lesegeräten nicht unterstützt.

   Datenschutz – „Bluetooth Always Usage Description“
   Schlüssel	NSBluetoothAlwaysUsageDescription
   Wert	Diese App verwendet Bluetooth, um sich mit unterstützten Kartenlesegeräten zu verbinden.

   iOS 13 führte spezifischere Berechtigungen für die Verwendung von Bluetooth-Peripheriegeräten durch eine App ein. Apps, die sich mit Core Bluetooth verbinden, müssen diesen Schlüssel in ihre Info.plist-Datei aufnehmen, um zu verhindern, dass die App beim ersten Start abstürzt.

4. App-Validierungsprüfungen bestehen, wenn Sie sie an den App Store übermittlen. Ab SDK-Version 3.4.0 ist diese Berechtigung nicht mehr erforderlich.

   Datenschutz – „Bluetooth Peripheral Usage Description“
   Schlüssel	NSBluetoothPeripheralUsageDescription
   Wert	Für die Verbindung mit unterstützten Kartenlesegeräten ist Bluetooth-Zugriff erforderlich.

   Es handelt sich hierbei um ein Beispiel – Sie können die Aufforderung zur Nutzerberechtigung in Ihrer App umformulieren.

Speichern Sie die Info.plist Ihrer App. Die App ist jetzt korrekt konfiguriert und kann mit dem Stripe Terminal SDK verwendet werden.

Serverseitig

Um sich mit einem Lesegerät verbinden zu können, muss das Backend dem SDK erlauben, das Lesegerät in Ihrem Stripe-Konto zu nutzen. Dazu stellt es dem SDK das Geheimnis aus einem ConnectionToken zur Verfügung. Das Backend muss nur Verbindungstoken für vertrauenswürdige Clients erstellen.

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

Beziehen Sie das Geheimnis aus dem ConnectionToken auf Ihrem Server und übergeben Sie es an den Client.

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

Clientseitig

Um dem SDK Zugriff auf diesen Endpoint zu ermöglichen, implementieren Sie das ConnectionTokenProvider-Protokoll in Ihrer App, das eine einzelne Funktion definiert, die einen ConnectionToken von Ihrem Backend anfordert.

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

Diese Funktion wird aufgerufen, wenn das SDK sich bei Stripe oder dem Lesegerät authentifizieren muss. Sie wird auch aufgerufen, wenn ein neues Verbindungstoken benötigt wird, um sich mit einem Lesegerät zu verbinden (z. B. wenn Ihre App sich von einem Lesegerät getrennt hat). Wenn das SDK kein neues Verbindungstoken von Ihrem Backend abrufen kann, schlägt die Verbindung zu einem Lesegerät mit einem Fehler von Ihrem Server fehl.

Die vom Stripe Terminal SDK bereitgestellte Terminal-Klasse stellt eine allgemeine Schnittstelle zum Erkennen von Lesegeräten, zum Verbinden mit einem Lesegerät und zum Durchführen von Vorgängen auf dem Lesegerät bereit, wie z. B. Anzeigen von Warenkorbdetails, Erfassen von Zahlungen und Speichern von Karten für die zukünftige Verwendung.

Geben Sie als Erstes Ihren in Schritt 3 implementierten ConnectionTokenProvider an. Sie können setTokenProvider nur einmal in Ihrer App aufrufen und müssen es vor dem Zugriff auf Terminal.shared aufrufen. Wir empfehlen, setTokenProvider in der Methode application:didFinishLaunchingWithOptions Ihres AppDelegates aufzurufen. Alternativ können Sie dispatch_once in Objective-C oder einen Konstruktor vom Typ static in Swift verwenden.

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
    }

    // ...

}