Verbindung zum Terminaldienst herstellen

Sobald das SDK initialisiert ist, muss Ihre App explizit eine Verbindung zum SoftPOS-Dienst herstellen, bevor Zahlungs-, Konfigurations-, Batch- oder Identifizierungsvorgänge aufgerufen werden können. Die Verbindung wird asynchron hergestellt und liefert Informationen zur ausgehandelten API-Version.

1. Verbinden (Kotlin-Coroutinen)

Kotlin

val sdk = (application as MyApplication).atiSdk

lifecycleScope.launch {
    try {
        val info = sdk.connect()
        val apiVersion = info.apiVersion
        // SDK is ready
    } catch (error: AtiSdkException) {
        // Handle connection failure (service not installed, permission missing, bind rejected)
    }
}

2. Verbinden (Java-Callback)

Java

sdk.connect(new TerminalCallback<AtiConnectionInfo>() {
    @Override
    public void onSuccess(AtiConnectionInfo info) {
        int apiVersion = info.getApiVersion();
        // SDK is ready
    }

    @Override
    public void onFailure(TerminalException error) {
        // Handle connection failure
    }
});

3. Nach Beendigung der Arbeit den Anschluss trennen

Lösen Sie die Bindung auf, sobald Ihre Integration den Terminal-Dienst nicht mehr benötigt – in der Regel, wenn sich der Benutzer abmeldet oder die Zahlungsoberfläche geschlossen wird:

Kotlin

sdk.disconnect()

Das SDK trennt die Verbindung nicht automatisch. Lang andauernde inaktive Verbindungen verschwenden eine Service-Bindung; stellen Sie bei Bedarf eine neue Verbindung her, wenn Ihre App längere Ruhephasen aufweist.

Wann sollte man eine Verbindung herstellen?

Stellen Sie die Verbindung bei der ersten Nutzung der Zahlungsoberfläche her, nicht beim Start der App. Ein „Kaltstart“ der Bindung, bevor der Nutzer sie benötigt, verlangsamt den Startvorgang und kann fehlschlagen, wenn die SoftPOS-App gerade aktualisiert wird.
Stellen Sie die Verbindung einmal pro Sitzung her. Das Ergebnis wird intern zwischengespeichert; nachfolgende Aufrufe werden schnell zurückgegeben.
Überprüfen Sie stets die ausgehandelten apiVersion- und Gate-Funktionen, die Ihre App nutzt, anhand dieser Angaben. Die Terminal-API befindet sich in aktiver Entwicklung, und die verfügbaren Funktionen können je nach Version variieren.

Fehlerarten bei der Verbindung

SoftPOS-App nicht installiert oder noch nicht aktiviert: Die Bindung schlägt fehl. Fordern Sie den Benutzer auf, die Schritte 2 und 3 des „Happy Path“ auszuführen.
Berechtigung fehlt oder <queries>-Block fehlt: Die Bindung wird unter Android 11+ stillschweigend abgelehnt. Überprüfen Sie die Manifest-Einstellungen.
SoftPOS-Dienst wird aktualisiert oder neu gestartet: vorübergehender Fehler. Mit einer Wartezeit erneut versuchen.
API-Versionskonflikt: Der verbundene Dienst unterstützt Ihre SDK-Version möglicherweise nicht. Überprüfen Sie apiVersion und zeigen Sie eine eindeutige Update-Meldung an.

Fehlerbehandlung

AtiSdkException umfasst den Verbindungsstatus und Fehler bei der Einrichtung auf niedrigerer Ebene (kein Dienst, Bind-Vorgang abgelehnt, SDK nicht initialisiert).
TerminalException wird nach dem Herstellen der Verbindung von den Terminal-Aufrufen selbst gemeldet – behandle dies bei jedem Vorgang und nicht bei connect() im Kotlin-Coroutine-Stil.

Empfohlenes Muster

Ordnen Sie das Verbinden/Trennen dem Lebenszyklus des zahlungsfähigen Bildschirms zu, nicht der gesamten App:

Kotlin

class CheckoutActivity : AppCompatActivity() {
    private val sdk by lazy { (application as MyApplication).atiSdk }

    override fun onStart() {
        super.onStart()
        lifecycleScope.launch {
            runCatching { sdk.connect() }
                .onFailure { /* show error */ }
        }
    }

    override fun onStop() {
        sdk.disconnect()
        super.onStop()
    }
}

Die vollständige Kompatibilitätsmatrix für Schemata und Versionen von AtiConnectionInfo finden Sie in der Terminal-API-Referenz.

Verbindung zum Terminaldienst herstellen​

Verbindung zum Terminaldienst herstellen