Integration einrichten

Um das SDK zu installieren, fügen Sie stripeterminal dem Block dependencies der Build-Datei Ihrer App hinzu:

plugins {
  id("com.android.application")
}

android { ... }

dependencies {
  implementation("com.stripe:stripeterminal:4.5.0")
  // ...
}

Da das SDK auf Java 8 basiert, muss diese Version als Ihre Java-Zielversion angegeben werden:

android {
  // ...
    compileOptions {
        sourceCompatibility = JavaVersion.VERSION_1_8
        targetCompatibility = JavaVersion.VERSION_1_8
    }
    kotlinOptions {
        jvmTarget = "1.8"
    }
}

Sie müssen die Berechtigung ACCESS_FINE_LOCATION aktivieren. Um eine Verbindung zu einem Bluetooth-Lesegerät herzustellen, müssen Sie auch Blueteooth-Berechtigungen aktivieren. Fügen Sie Ihrem Manifest die entsprechenden Berechtigungen hinzu, wie hier dargestellt:

<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.BLUETOOTH" android:maxSdkVersion="30" />
<uses-permission android:name="android.permission.BLUETOOTH_ADMIN" android:maxSdkVersion="30" />
<uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />
<uses-permission android:name="android.permission.BLUETOOTH_SCAN" />

Bevor Sie das Terminal-Objekt initialisieren, fügen Sie die folgende Prüfung hinzu, um sicherzustellen, dass die Berechtigung ACCESS_FINE_LOCATION in Ihrer App aktiviert ist:

if (ContextCompat.checkSelfPermission(this, android.Manifest.permission.ACCESS_FINE_LOCATION) != PackageManager.PERMISSION_GRANTED) {
    val permissions = arrayOf(android.Manifest.permission.ACCESS_FINE_LOCATION)
    ActivityCompat.requestPermissions(this, permissions, REQUEST_CODE_LOCATION)
}

Prüfen Sie außerdem, ob der/die Nutzer/in der App die Standortberechtigung erteilt – ohne diese funktioniert das SDK nicht. Überschreiben Sie dazu die Methode onRequestPermissionsResult in Ihrer App und überprüfen Sie das Berechtigungsergebnis.

override fun onRequestPermissionsResult(
    requestCode: Int,
    permissions: Array<String>,
    grantResults: IntArray
) {
    super.onRequestPermissionsResult(requestCode, permissions, grantResults)

    if (requestCode == REQUEST_CODE_LOCATION && grantResults.isNotEmpty()
        && grantResults[0] != PackageManager.PERMISSION_GRANTED
    ) {
        throw RuntimeException("Location services are required to connect to a reader.")
    }
}

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 die ConnectionTokenProvider-Schnittstelle in Ihrer App, die eine einzelne Funktion definiert, die einen ConnectionToken aus Ihrem Backend anfordert.

class CustomConnectionTokenProvider : ConnectionTokenProvider {
    override fun fetchConnectionToken(callback: ConnectionTokenCallback) {
        try {
            // Your backend should call /v1/terminal/connection_tokens and return the
            // JSON response from Stripe. When the request to your backend succeeds,
            // return the `secret` from the response to the SDK.
            callback.onSuccess(secret)
        } catch (e: Exception) {
            callback.onFailure(
                ConnectionTokenException("Failed to fetch connection token", e)
            )
        }
    }
}

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.

Das Android SDK berücksichtigt den Lebenszyklus. Um Speicherlecks zu vermeiden und eine ordnungsgemäße Bereinigung von über einen langen Zeitraum ausgeführten Terminal-SDK-Prozessen zu gewährleisten, muss Ihre Anwendung eine Application-Unterklasse implementieren, die TerminalApplicationDelegate.onCreate() verwendet, um das SDK über Ereignisse im Lebenszyklus zu informieren.

// Substitute with your application name, and remember to keep it the same as your AndroidManifest.xml
class StripeTerminalApplication : Application() {
    override fun onCreate() {
        super.onCreate()
        TerminalApplicationDelegate.onCreate(this)
    }
}

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 Ausfü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.

Stellen Sie zunächst den aktuellen Anwendungskontext, den in Schritt 3 implementierten ConnectionTokenProvider und ein TerminalListener-Objekt bereit. Sie können diesen Listener verwenden, um Ereignisse wie Zahlungen und Aktualisierungen des Verbindungsstatus über das SDK zu verarbeiten.

// Create your listener object. Override any methods that you want to be notified about
val listener = object : TerminalListener {
    override fun onConnectionStatusChange(status: ConnectionStatus) {
        println("onConnectionStatusChange: $status");
    }

    override fun onPaymentStatusChange(status: PaymentStatus) {
        println("onPaymentStatusChange: $status");
    }
}

// Choose the level of messages that should be logged to your console
val logLevel = LogLevel.VERBOSE

// Create your token provider.
val tokenProvider = CustomConnectionTokenProvider()

// Pass in the current application context, your desired logging level, your token provider, and the listener you created
if (!Terminal.isInitialized()) {
    Terminal.initTerminal(applicationContext, logLevel, tokenProvider, listener)
}

// Since the Terminal is a singleton, you can call getInstance whenever you need it
Terminal.getInstance()