Workspace Android SDK einrichten

Mit dem offiziellen Android SDK verbinden Sie eine eigene Workforce- oder Administrations-App mit Workspace. Dieser Quickstart richtet sich an Android-Entwickler. Nach Abschluss erkennt Ihre App den Serververtrag, führt den Headless-Login aus und speichert die Sitzung verschlüsselt.

> Verwenden Sie das Android SDK für native Kotlin- und Java-Apps. Flutter gehört noch nicht zum unterstützten SDK-Umfang. Serverseitige Integrationen verwenden die releasegebundenen Go-, Node.js- und PHP-SDKs, sobald die gewünschte Version im jeweiligen Paketregister verfügbar ist.

> Das Android-SDK ist für Maven Central vorbereitet, dort aber noch nicht > veröffentlicht. Warten Sie für produktive Integrationen auf das passende > öffentliche Maven-Central-Artefakt. Ein Workspace-Release allein garantiert > noch kein öffentlich verfügbares SDK-Paket derselben Version. Die folgenden > Schritte dienen bis dahin als Vorabreferenz.

Voraussetzungen

  • Android API 26 oder neuer
  • eine per HTTPS erreichbare Workspace-Installation
  • einen Workforce- oder Administrationsbenutzer
  • dieselbe Versionsnummer für Workspace und SDK

Abhängigkeit einbinden

kotlin
dependencies {
    implementation("com.schukai.nucleus:nucleus-sdk-android:<workspace-version>")
}

Verwenden Sie keine unabhängig ausgewählte SDK-Version. Jedes Workspace-Release erzeugt den passenden SDK-Vertrag und die zugehörigen Maven-Artefakte.

Client erstellen

kotlin
val sessions = AndroidSecureSessionStore(applicationContext)
val nucleus = NucleusClient.create("https://workspace.example.com/", sessions)
val discovery = nucleus.discover()

Prüfen Sie discovery.apiMajor, bevor Sie fortfahren. Aktivieren Sie optionale Funktionen ausschließlich über capabilities und veröffentlichte Entrypoints. Leiten Sie Fähigkeiten nicht aus serverVersion ab.

Anmelden

kotlin
val result = nucleus.login(email, password)
when (result.state) {
    AuthStates.READY_SESSION -> openWorkspace(result.activeTenantId)
    AuthStates.CHALLENGE_REQUIRED -> requestSecondFactor(result.challenge!!.token)
    AuthStates.SELECTION_REQUIRED -> showTenants(result.tenantCandidates)
    AuthStates.LICENSE_AGREEMENT_REQUIRED -> showAgreementNotice(result.agreement)
}

Das SDK speichert eine ausgegebene Sitzung mit Android Keystore und AES-GCM. Protokollieren Sie niemals Passwörter, Sitzungs- oder Challenge-Tokens, Bootstrap-Grants, Cookies oder vollständige Fehlerantworten.

Beim Status AuthStates.LICENSE_AGREEMENT_REQUIRED liefert das SDK nur die Metadaten der Vereinbarung. canAccept zeigt, ob die Identity die Vereinbarung im geschützten Browserflow annehmen darf. Unabhängig von diesem Wert gibt Workspace in diesem Zustand weder eine Sitzung noch einen Bootstrap-Grant aus. Öffnen Sie für die Bestätigung den konfigurierten Workspace-Browserflow. Leiten Sie aus agreement.routeKey keine URL ab. Das SDK bietet dafür bewusst keine Headless-Aktion an.

Serveraktionen ausführen

Ein Ressourcen-Entrypoint kann statt einer direkten HTTP-Methode eine Liste strukturierter actions enthalten. Wählen Sie die Aktion über ihre stabile ID und rufen Sie executeAction() auf. Übergeben Sie genau die in requiredHeaders angekündigten Header. Das SDK prüft den erwarteten Status und gibt nur die in responseHeaders freigegebenen Antwortheader zurück.

Ergebnis prüfen

Die Einrichtung ist erfolgreich, wenn discover() den API-Major v1 liefert und login() einen dokumentierten Authentifizierungsstatus zurückgibt. Nach dem Status AuthStates.READY_SESSION liefert resourceEntrypoints() ausschließlich die für Benutzer und Mandant erlaubten Ressourcen.

Behandeln Sie Fehler anhand von HTTP-Status und stabilem errorCode. Übersetzen Sie die Benutzeranzeige in Ihrer App; das SDK liefert in dieser Version bewusst keine Laufzeitübersetzungen aus.