# Terminal SDK V3-Migrationsleitfaden Erfahren Sie, wie Sie zur Version 3.0.0 des Stripe Terminal SDK migrieren. Die iOS und Android SDKs für Stripe Terminal wurden mit einer Reihe wichtiger Änderungen an APIs und Verhalten aktualisiert, von denen einige erfordern, dass Sie Ihre Integration mit dem Stripe Terminal SDK aktualisieren. Wir nehmen regelmäßig Änderungen an wichtigen Versionsaktualisierungen vor, die sich auf die Funktionsweise oder das Verhalten Ihrer Integration auswirken können, um die Konsistenz zwischen unseren SDKs zu verbessern und Ihre Anwendungslogik und Integration zu vereinfachen. Dieser Leitfaden führt Sie durch die neuesten Änderungen und hilft Ihnen beim Upgrade Ihrer Integration. > Erstellen Sie gerade eine neue Stripe Terminal-Integration? Auf unserer Seite zum [Entwerfen einer Integration](https://docs.stripe.com/terminal/designing-integration.md) erfahren Sie, wie Sie beginnen können. ## Migration zu Version 3.0.0 Hier erfahren Sie, was Sie über die Stripe Terminal iOS und Android SDKs 3.0.0 wissen müssen: - Unterstützung für die Verarbeitung von Offline-Zahlungen - Diese Funktion für den Offline-Modus befindet sich derzeit in der privaten Vorschau. Um Zugriff anzufordern, wenden Sie sich an [stripe-terminal-betas@stripe.com](mailto:stripe-terminal-betas@stripe.com). Nachdem wir die Änderungen für Ihr Konto im Backend aktiviert haben, müssen Sie mithilfe des SDK die Verbindung zu Ihrem Lesegerät trennen und erneut herstellen, damit die aktualisierte Konfiguration wirksam wird. - Aktualisierungen der unterstützten Mindestversionen der Plattformen für iOS und Android - Entfernung abgeschaffter Funktionen und Eigenschaften # iOS > This is a iOS for when terminal-sdk-platform is ios. View the full page at https://docs.stripe.com/terminal/references/sdk-v3-migration-guide?terminal-sdk-platform=ios. Wenn Ihre Anwendung zurzeit eine Terminal iOS SDK-Version vor 3.0.0. verwendet, müssen Sie einige Änderungen vornehmen, um ein Upgrade vorzunehmen und weltweit Card-Present-Zahlungen zu akzeptieren. Eine detaillierte Liste der Änderungen von Version 2.23.1 auf 3.0.0 finden Sie im [SDK-Änderungsprotokoll](https://github.com/stripe/stripe-terminal-ios/releases/tag/v3.0.0). ## Aktualisieren Sie Ihre unterstützte Mindestversion auf iOS 13 oder höher Wir aktualisieren regelmäßig die unterstützte Mindestversion unserer SDKs, um unseren Entwicklerinnen und Entwicklern die bestmögliche Erfahrung zu bieten. Vorhandene 2.X-Versionen des Terminal iOS SDK unterstützen weiterhin Geräte mit **iOS 11** und höher. ## Aktualisieren Sie Ihre Nutzung der DiscoveryConfigurationauf die spezifische DiscoveryConfiguration-Implementierung Um die Konfiguration für verschiedene Erkennungsmethoden zu unterstützen, ist [SCPDiscoveryConfiguration](https://stripe.dev/stripe-terminal-ios/docs/Protocols/SCPDiscoveryConfiguration.html) jetzt ein Protokoll, das von mehreren verschiedenen Typen implementiert wird. Statt einer DiscoveryMethod stehen nun einzelne Klassen zur Auswahl, um nach einem bestimmten Lesegerät zu suchen: | Konfigurationsklasse | Nutzung | | --------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | | [SCPBluetoothScanDiscoveryConfiguration](https://stripe.dev/stripe-terminal-ios/docs/Classes/SCPBluetoothScanDiscoveryConfiguration.html) | Bluetooth-fähige Lesegeräte in der Nähe dieses iOS-Geräts | | [SCPBluetoothProximityDiscoveryConfiguration](https://stripe.dev/stripe-terminal-ios/docs/Classes/SCPBluetoothProximityDiscoveryConfiguration.html) | Eine Teilmenge der Bluetooth-fähigen Lesegeräte in der Nähe dieses iOS-Geräts | | [SCPInternetDiscoveryConfiguration](https://stripe.dev/stripe-terminal-ios/docs/Classes/SCPInternetDiscoveryConfiguration.html) | Internetfähige Lesegeräte, die für dieses Konto registriert sind | | [SCPLocalMobileDiscoveryConfiguration](https://stripe.dev/stripe-terminal-ios/docs/Classes/SCPLocalMobileDiscoveryConfiguration.html) | [Tap to Pay](https://docs.stripe.com/terminal/payments/setup-reader/tap-to-pay.md?platform=ios) unter Verwendung des NFC-Lesegeräts dieses iOS-Geräts | Erstellen Sie die für Ihre gewünschte Erkennungsmethode geeignete Erkennungskonfiguration mithilfe der angegebenen Builder-Klasse und geben Sie diese für `discoverReaders` an. Der Builder macht Setter für die Eigenschaften verfügbar, die von jeder Konfiguration unterstützt werden. ## Aktualisieren Sie die Nutzung Ihrer discoverReader und connectReader - Das Abbrechen von `discoverReaders` ruft jetzt den Completion-Block mit einem Fehler mit dem Code `SCPErrorCanceled` auf , genau wie alle anderen annulierbaren Methoden. - `discoverReaders` wird jetzt erfolgreich abgeschlossen, wenn `connectReader` aufgerufen wird. Wenn `connectReader` fehlschlägt, muss Ihre Integration einen neuen Aufruf von `discoverReaders` durchführen, um die Suche nach Lesegeräten fortzusetzen. - `discoverReaders` muss nicht mehr ausgeführt werden, damit `connectReader` funktioniert. Sie können jetzt `connectReader` mit einer zuvor erkannten Lesegerät-Instanz aufrufen oder die Verbindung erneut versuchen, ohne `discoverReaders` neu zu starten. ## Aktualisieren Sie Ihre ReconnectionDelegate-Implementierung `SCPReconnectionDelegate` liefert jetzt die Instanz des Lesegeräts, mit der die Verbindung wieder hergestellt wird, statt der Terminal-Instanz. Wenn Sie diese Aufgabe zuvor implementiert haben, müssen Sie `terminal` in den Methodennamen durch `reader` ersetzen. ## Aktualisieren der Nutzung von Parametern der Konfigurationsklasse, um Builders zu verwenden Die Eingabeklassen wie `SCPCollectConfiguration` und `SCPPaymentIntentParameters` sind jetzt unveränderlich und verfügen über zugehörige Builder, um sie zu erstellen. Alle Builder verfügen über eine Build-Methode, die die Eingaben validiert und die erstellte Klasse aufbaut. - In Swift wird `build()` ausgelöst und sollte auf Fehler überprüft werden. - In Objective-C geben Sie den `NSError **` an, um den Fehler (falls vorhanden) zu empfangen. ```swift let paymentParams = try PaymentIntentParametersBuilder(amount: 100, currency: "cad") .setCaptureMethod(.automatic) .build() ``` ## Entfernen Sie jegliche Abhängigkeit von SCPErrorBusy `SCPErrorBusy` wurde entfernt. Wenn Sie in SDK 3.0.0 und höher eine Terminal-Methode aufrufen, während eine andere noch aktiv ist, werden die neuen Aufrufe jetzt in die Warteschlange gestellt. Die Befehle werden ausgeführt, nachdem alle vorherigen Befehle abgeschlossen wurden. Wenn Sie zuvor den Status verfolgt haben, um `SCPErrorBusy` zu verhindern, oder Ihre eigenen Befehle in die Warteschlange gestellt haben, um `SCPErrorBusy` zu umgehen, können Sie jetzt die Befehlswarteschlange verwenden, um Ihren Code zu vereinfachen. Wenn Ihre Anwendung sich auf `SCPErrorBusy` verlässt, um zu wissen, ob ein Befehl ausgeführt wird, überprüfen Sie Ihren Code, um zu sehen, ob dies zu Problemen mit dem Einreihen zu vieler Befehle in die Warteschlange führen könnte. ## Überprüfen Sie die Unterstützung für Offline-Zahlungen `SCPPaymentIntent.stripeId` ist für Offline-Zahlungen null. Wenn Ihre Integration nur Online-Zahlungen unterstützt, ist die `stripeId` immer vorhanden und es sind keine Änderungen erforderlich, abgesehen von Überprüfungen der ID. Weitere Informationen zur Offline-Verarbeitung von Zahlungen finden Sie unter [Kartenzahlungen offline einziehen](https://docs.stripe.com/terminal/features/operate-offline/collect-card-payments.md?terminal-sdk-platform=ios). ```swift Terminal.shared.createPaymentIntent(params) { intent, error in if let error = error { // Placeholder for handling exception } guard let intentId = intent.stripeId else { // PaymentIntent was created offline without an id. See intent.offlineDetails. // This is only expected when offline mode is enabled. } } ``` ## Aktualisieren Sie Ihre Prozessaufrufe zur Bestätigung `SCPTerminal.processPayment` wird in `SCPTerminal.confirmPaymentIntent` und `SCPTerminal.processRefund` wird in `SCPTerminal.confirmRefund` umbenannt. Die Parameter für diese Methoden wurden nicht geändert, aber die Fehlertypen wurden ebenfalls in `SCPConfirmPaymentIntentError` bzw. `SCPConfirmRefundError` umbenannt. ## Ändern Sie Ihre readReusableCard-Nutzung in SetupIntents `SCPTerminal.readReusableCard` wurde entfernt. SetupIntents sind der empfohlene Pfad zum Speichern von Zahlungsmethoden ohne Abbuchung. SetupIntents folgen einem ähnlichen Muster wie PaymentIntents, bei dem Sie den SetupIntent im SDK erstellen, erfassen und bestätigen. Weitere Informationen finden Sie unter [Zahlungsdaten für die Online-Wiederverwendung speichern](https://docs.stripe.com/terminal/features/saving-payment-details/overview.md). # Android > This is a Android for when terminal-sdk-platform is android. View the full page at https://docs.stripe.com/terminal/references/sdk-v3-migration-guide?terminal-sdk-platform=android. Wenn Ihre Anwendung derzeit eine Terminal Android SDK-Version vor 3.0.0 verwendet, müssen Sie einige Änderungen vornehmen, um ein Upgrade vorzunehmen und weltweit Card-Present-Zahlungen zu akzeptieren. Eine detaillierte Liste der Änderungen von Version 2.23.1 auf 3.0.0 finden Sie im [SDK changelog](https://github.com/stripe/stripe-terminal-android/blob/master/CHANGELOG.md). ## Aktualisieren Sie Ihre unterstützte Mindestversion auf Android 8 oder höher Zukünftige Versionen des Terminal Android SDK werden nur noch Geräte unterstützen, auf denen **Android 8.0 „Oreo“ (API 26)** oder höher ausgeführt wird. Wir aktualisieren regelmäßig die unterstützte Mindestversion unserer SDKs, um unseren Entwicklerinnen und Entwicklern die bestmögliche Erfahrung zu bieten. Beachten Sie, dass der Versuch, die `minSdkVersion` zu überschreiben, um die minimal unterstützte API-Stufe zu verringern, aufgrund der internen Validierung auf API-Ebene nicht funktioniert. Vorhandene 2.X-Versionen des Terminal Android SDK unterstützen weiterhin Geräte mit **Android 5.0 „Lollipop“ (API 21)** und höher. ## Aktualisieren Sie Ihre DiscoveryConfiguration-Nutzung Um die Konfiguration für verschiedene Erkennungsmethoden zu unterstützen, ist die [DiscoveryConfiguration](https://stripe.dev/stripe-terminal-android/external/com.stripe.stripeterminal.external.models/-discovery-configuration/index.html)-Klasse jetzt eine Schnittstelle, die von mehreren verschiedenen versiegelten Unterklassen implementiert wird. Statt einer DiscoveryMethod stehen nun einzelne Klassen zur Auswahl, um nach einem bestimmten Lesegerät zu suchen: | Konfigurationsklasse | Nutzung | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [BluetoothDiscoveryConfiguration](https://stripe.dev/stripe-terminal-android/external/com.stripe.stripeterminal.external.models/-discovery-configuration/-bluetooth-discovery-configuration/index.html) | Bluetooth-fähige Lesegeräte in der Nähe dieses Android-Geräts | | [UsbDiscoveryConfiguration](https://stripe.dev/stripe-terminal-android/external/com.stripe.stripeterminal.external.models/-discovery-configuration/-usb-discovery-configuration/index.html) | Über USB mit diesem Android-Gerät verbundene Lesegeräte | | [InternetDiscoveryConfiguration](https://stripe.dev/stripe-terminal-android/external/com.stripe.stripeterminal.external.models/-discovery-configuration/-internet-discovery-configuration/index.html) | Internetfähige Lesegeräte, die für dieses Konto registriert sind | | [LocalMobileDiscoveryConfiguration](https://stripe.dev/stripe-terminal-android/external/com.stripe.stripeterminal.external.models/-discovery-configuration/-local-mobile-discovery-configuration/index.html) | [Tap to Pay](https://docs.stripe.com/terminal/payments/setup-reader/tap-to-pay.md?platform=android) unter Verwendung des NFC-Lesegeräts dieses Android-Geräts | | [HandoffDiscoveryConfiguration](https://stripe.dev/stripe-terminal-android/external/com.stripe.stripeterminal.external.models/-discovery-configuration/-handoff-discovery-configuration/index.html) | [Apps auf Geräten](https://docs.stripe.com/terminal/features/apps-on-devices/overview.md) für Android-Geräte mit Stripe SmartPOS | ## Aktualisieren Sie Ihre Lesegeräterkennung, um Berechtigungsanfragen zur Laufzeit durchzuführen Bisher erforderte das SDK, dass der Anwendung bei der SDK-Initialisierung Standort- und Bluetooth-Berechtigungen gewährt wurden, wenn `Terminal.initTerminal()` aufgerufen wurde. Dies war übermäßig streng und erforderte häufig, dass Integrationen, die keine Verbindung zu Bluetooth-Lesegeräten herstellten, trotzdem Bluetooth-Berechtigungen erteilen mussten, um das SDK verwenden zu können. Diese Anforderung wurde nun gelockert, sodass Berechtigungen jetzt zum Zeitpunkt der Erkennung des Lesegeräts überprüft werden und nur der Mindestsatz an Berechtigungen abhängig von der `DiscoveryConfiguration` erzwungen wird. Standortberechtigungen sind immer noch erforderlich, aber die Überprüfung, ob diese Berechtigungen erteilt wurden, verzögert sich jetzt bis zur Lesegeräterkennung für jede `DiscoveryConfiguration`. Bluetooth-Berechtigungen werden jetzt auch bei der Lesegeräterkennung geprüft, sie sind jedoch nur erforderlich, wenn nach Lesegeräten mit einer `BluetoothDiscoveryConfiguration` gesucht wird. ## Überprüfen Sie die Änderung des Verbindungsstatus des Lesegeräts, wenn Sie erforderliche Updates installieren Wenn Sie versuchen, über Bluetooth oder USB eine Verbindung zu einem Lesegerät herzustellen, für das Aktualisierungen erforderlich sind, müssen diese Aktualisierungen angewendet werden, damit die Verbindung erfolgreich hergestellt werden kann. Zuvor wurde der Callback `TerminalListener.onConnectionStatusChange()` Ihrer Integration mit `CONNECTED` und `TerminalListener.onPaymentStatusChanged()` mit `READY` aufgerufen, sobald die Verbindung hergestellt wurde. Wenn am Lesegerät jedoch erforderliche Aktualisierungen durchgeführt werden müssten, wurden diese während des Empfangs dieser Rückrufe installiert, was die Annahme von Befehlen durch das Lesegerät erst nach deren Abschluss verzögerte. Der Status des Lesegeräts bleibt jetzt `CONNECTING`, während alle erforderlichen Updates installiert werden. Erst nachdem diese erforderlichen Aktualisierungen erfolgreich abgeschlossen wurden, wird Ihre Integration benachrichtigt, dass das Lesegerät jetzt verbunden und einsatzbereit ist. ## Überprüfen Sie die Unterstützung für Offline-Zahlungen `PaymentIntent.id` ist für Offline-Zahlungen null. Wenn Ihre Integration nur Online-Zahlungen unterstützt, ist die `id` immer vorhanden und es sind keine Änderungen erforderlich, abgesehen von Überprüfungen der ID. Weitere Informationen zur Offline-Verarbeitung von Zahlungen finden Sie unter [Kartenzahlungen offline einziehen](https://docs.stripe.com/terminal/features/operate-offline/collect-card-payments.md?terminal-sdk-platform=android). ```kotlin Terminal.getInstance().createPaymentIntent( params, object : PaymentIntentCallback { override fun onSuccess(paymentIntent: PaymentIntent) { val intentId = paymentIntent.id ?: run { // PaymentIntent was created offline without an id. See intent.offlineDetails. // This is only expected when offline mode is enabled. } } override fun onFailure(e: TerminalException) { // Placeholder for handling exception } } ) ``` ## Aktualisieren Sie Ihre Prozessaufrufe zur Bestätigung `Terminal.processPayment()` wird in `Terminal.confirmPaymentIntent()` und `Terminal.processRefund()` wird in `Terminal.confirmRefund()` umbenannt. Nur der Name der Methode wird geändert, das Verhalten dieser Methoden bleibt identisch. ## Nutzung von Parcelable-Datenmodellen aktualisieren, um serialisierbare Methoden zu verwenden Wenn Ihre Integration das Lesen und Schreiben von Terminal SDK-Datenmodellen in ein Parcel erfordert, müssen Sie Ihre `writeParcelable()`- und `readParcelable()`-Aufrufe mit `writeSerializable()` und `readSerializable()` aktualisieren. Wie bei `Parcelable`-Datenmodellen wird empfohlen, keine `Serializable`-Daten im dauerhaften Speicher zu platzieren: Änderungen an der zugrunde liegenden Implementierung der Daten in einem `Serializable`-Datenmodell zwischen SDK-Aktualisierungen, z. B. das Hinzufügen neuer Felder, können ältere Daten unlesbar machen. ## Ändern Sie Ihre readReusableCard-Nutzung in SetupIntents `Terminal.readReusableCard()` wurde entfernt. SetupIntents sind der empfohlene Pfad zum Speichern von Zahlungsdetails ohne Abbuchung. SetupIntents folgen einem ähnlichen Muster wie PaymentIntents, bei dem Sie den SetupIntent im SDK erstellen, erfassen und bestätigen. Weitere Informationen finden Sie unter [Zahlungsdaten für Online-Zahlungen speichern](https://docs.stripe.com/terminal/features/saving-payment-details/overview.md). ## Nutzung von umbenannten oder entfernten, abgeschafften APIs aktualisieren Einige abgeschaffte Klassen, Felder und Methoden wurden aus dem SDK entfernt. Die meisten APIs, die entfernt wurden, verfügen bereits über Ersatzfelder, die stattdessen gelesen werden können. - `CaptureMethod.getManual()` wird entfernt. Verwenden Sie stattdessen `CaptureMethod.MANUAL`. - Der Konstruktor `CollectConfiguration` wird entfernt. Verwenden Sie stattdessen `CollectConfiguration.Builder` . - `CollectConfiguration.moto` kann nicht mehr geändert werden. - `ConnectConfiguration.registerToLocation` wird entfernt und durch `ConnectConfiguration.locationId` ersetzt. - Der Parameter `locationId` aus dem Konstruktor `HandoffConnectionConfiguration` wurde entfernt. - `BluetoothReaderListener` und `UsbReaderListener` wurden entfernt und durch `ReaderListener` ersetzt. - `EmvBlob` ist als interne Klasse gekennzeichnet. - `Reader.device` wurde entfernt und durch `Reader.bluetoothDevice` und `Reader.usbDevice` ersetzt. - `Reader.registeredLocation` wurde entfernt und durch `Reader.location` ersetzt. - `TerminalApplicationDelegate.onTrimMemory()` wurde entfernt. Es wird automatisch vom SDK verwaltet. - `CardDetails.fingerprint` und `CardPresentDetails.fingerprint` wurden entfernt. Mithilfe von [serverseitigen SDKs](https://docs.stripe.com/sdks.md#server-side-libraries) von Stripe können Sie weiterhin auf den Fingerabdruck zugreifen.