Transloadit

Android SDK

transloadit/android-sdk

Installation

Diese Anleitung verwendet das Android SDK 0.2.0 mit dem Java SDK 2.2.4. Das Android-Paket ist ein AAR und über Maven Central verfügbar. Sein veröffentlichtes POM enthält keine Abhängigkeiten. Fügen Sie das Java SDK explizit hinzu und binden Sie die Android-Abhängigkeiten aus dem Build mit Versions-Tag ein, wenn Sie die Android-APIs für Listener und Persistenz integrieren. Prüfen Sie diese Zusammenstellung von Abhängigkeiten in Ihrer App.

Gradle:

implementation 'com.transloadit.android.sdk:transloadit-android:0.2.0'
implementation 'com.transloadit.sdk:transloadit:2.2.4'

Maven:

<dependency>
  <groupId>com.transloadit.android.sdk</groupId>
  <artifactId>transloadit-android</artifactId>
  <version>0.2.0</version>
  <type>aar</type>
</dependency>
<dependency>
  <groupId>com.transloadit.sdk</groupId>
  <artifactId>transloadit</artifactId>
  <version>2.2.4</version>
</dependency>

Verwendung

Alle Interaktionen mit dem SDK beginnen mit der Klasse com.transloadit.android.sdk.AndroidTransloadit.

Authentifizierungsmethoden

Bewahren Sie das Auth Secret in Ihrem Backend auf, auch bei intern verteilten Apps. APK-Inhalte und heruntergeladene Konfigurationen können seine Vertraulichkeit nicht gewährleisten. Schreiben Sie Signature Authentication für den Workspace oder das Template vor, den beziehungsweise das die App verwendet. Der Auth Key darf der App bereitgestellt werden; das Auth Secret darf ihr niemals bereitgestellt werden.

Der Konstruktor mit Schlüssel und geheimem Schlüssel ist für einen Android-Client ungeeignet. Vertrauenswürdige Serveranwendungen können das Java SDK mit Zugangsdaten verwenden, die auf dem Server verbleiben.

Signature Authentication im Backend

Das SDK ruft SignatureProvider.generateSignature synchron mit exakt der serialisierten Zeichenfolge params auf, die es senden wird. Mit dem unten verwendeten Konstruktor fügt es auth, einen neuen Wert für nonce und einen Ablaufzeitpunkt fünf Minuten in der Zukunft hinzu. Ihr Backend muss diesen Ablaufzeitpunkt anhand seiner eigenen Uhr prüfen. Parsen und serialisieren Sie die Zeichenfolge vor dem Signieren nicht erneut und verwenden Sie eine Signatur nicht für andere Parameter wieder.

Implementieren Sie vor der Verwendung der folgenden Hilfsklasse deren Interface SigningBackend mit dem authentifizierten HTTPS-Client Ihrer App. Dieses Interface definiert die Integrationsschnittstelle Ihrer Anwendung und ist kein SDK-Dienst. Senden Sie die unveränderte Zeichenfolge paramsJson an Ihr eigenes Backend und das Sitzungstoken des aktuellen Benutzers im Header Authorization der Anfrage. Verwenden Sie einen festen, vertrauenswürdigen Endpunkt, lehnen Sie Weiterleitungen ab, begrenzen Sie das Zeitlimit für die Anfrage und lösen Sie bei Transportfehlern oder jeder erfolglosen HTTP-Antwort eine Ausnahme aus. Geben Sie die vom Backend freigegebene Parameterzeichenfolge und die Signatur als SignedParams zurück; geben Sie niemals das Auth Secret zurück.

Das Backend muss vor dem Signieren die Sitzung authentifizieren und den Upload dieses Benutzers autorisieren. Lassen Sie nur den erwarteten Auth Key, eine neue Nonce, den Ablaufzeitpunkt und exakt den unten gezeigten Step zur Größenänderung zu; lehnen Sie zusätzliche Steps, beliebige Templates, Felder oder Ziele ab. Wenden Sie Ihre Upload-Limits und Kontingentrichtlinien auf dem Server an. Deaktivieren Sie bei einem serverseitig verwalteten Template allow_steps_override und lassen Sie nur dieses Template zu. Angemeldet zu sein berechtigt nicht dazu, beliebiges JSON signieren zu lassen. Signieren Sie die freigegebenen ursprünglichen UTF-8-Bytes mit HMAC-SHA384 und geben Sie das Präfix sha384: gefolgt von den 96 Hexadezimalziffern zurück.

Assembly erstellen

Speichern Sie diese vollständige Hilfsklasse als MobileImageUpload.java. Sie bindet jede zurückgegebene Signatur an die exakten Parameter des SDK und lehnt fehlende Sitzungen, abweichende Parameter und fehlerhaft formatierte Signaturen ab. Die Autorisierung bleibt Aufgabe des Backends; diese clientseitigen Prüfungen können sie nicht ersetzen.

import com.transloadit.android.sdk.AndroidTransloadit;
import com.transloadit.sdk.Assembly;
import com.transloadit.sdk.SignatureProvider;
import java.io.File;
import java.util.HashMap;
import java.util.Map;
import java.util.Objects;

public final class MobileImageUpload {
  private MobileImageUpload() {}

  public static final class SignedParams {
    public final String params;
    public final String signature;

    public SignedParams(String params, String signature) {
      this.params = params;
      this.signature = signature;
    }
  }

  @FunctionalInterface
  public interface SigningBackend {
    SignedParams approve(String paramsJson, String userSessionToken) throws Exception;
  }

  public static AndroidTransloadit createClient(
      String authKey, String userSessionToken, SigningBackend backend) {
    Objects.requireNonNull(backend, "A signing backend is required");
    if (userSessionToken == null || userSessionToken.trim().isEmpty()) {
      throw new IllegalArgumentException("An authenticated user session is required");
    }
    SignatureProvider signatures = paramsJson -> {
      SignedParams approved = backend.approve(paramsJson, userSessionToken);
      if (approved == null || !paramsJson.equals(approved.params)
          || approved.signature == null
          || !approved.signature.matches("sha384:[0-9a-f]{96}")) {
        throw new IllegalStateException("Signing was not approved for these parameters");
      }
      return approved.signature;
    };
    return new AndroidTransloadit(authKey, signatures);
  }

  public static void addImage(Assembly assembly, File image) {
    assembly.addFile(image, "image");
    Map<String, Object> stepOptions = new HashMap<>();
    stepOptions.put("width", 75);
    stepOptions.put("height", 75);
    stepOptions.put("resize_strategy", "pad");
    assembly.addStep("resize", "/image/resize", stepOptions);
  }
}

Übergeben Sie Ihren Auth Key, das Sitzungstoken des aktuellen Benutzers und Ihre Backend-Implementierung an MobileImageUpload.createClient. Das Token authentifiziert Ihre Anfrage an das eigene Backend; es ist weder ein Auth Secret von Transloadit noch ein Transloadit-API-Token. Erneuern Sie eine abgelaufene Sitzung, bevor Sie einen neuen Client erstellen. Das SDK erstellt auth selbst, daher kann der Signatur-Callback weder auth.max_size noch auth.max_number_of_files hinzufügen. Wenn Ihre Richtlinie diese Limits erfordert, setzen Sie sie in einem serverseitig verwalteten Template durch oder erstellen Sie Assemblies im Backend. Die Anzahl der lokal hinzugefügten Dateien stellt keine serverseitige Autorisierungsgrenze dar.

Erstellen Sie eine Instanz von AndroidAssembly mit client.newAssembly(listener, context), übergeben Sie diese und ein lesbares lokales Bild an MobileImageUpload.addImage und rufen Sie dann assembly.saveAsync() auf. Stellen Sie eine Implementierung von AndroidAssemblyListener bereit, die onUploadProgress, onUploadFinished, onAssemblyFinished, onUploadFailed und onAssemblyStatusUpdateFailed implementiert. Der Abschluss des Uploads ist vom Abschluss der Verarbeitung getrennt. Prüfen Sie in der zurückgegebenen Antwort status() und hasError() und behandeln Sie zusätzlich Ausnahmen; API-Fehler werden nicht immer als Ausnahmen ausgelöst.

Das Signieren erfolgt synchron im Thread des Aufrufers. saveAsync() führt die Übermittlung der Assembly auf dem Executor des SDK aus; direkte synchrone SDK-Aufrufe müssen jedoch außerhalb des UI-Threads erfolgen. Listener-Callbacks verwenden in 0.2.0 standardmäßig den Hauptthread. Halten Sie die Assembly und den Listener in einem geeigneten Lifecycle-Owner, vermeiden Sie Referenzen auf eine bereits zerstörte Activity und verwalten Sie Abbrüche und Hintergrundarbeit in Ihrer App. Diese Hilfsklasse bietet weder eine Zeitplanung mit WorkManager noch die Wiederaufnahme von Uploads nach dem Beenden des Prozesses. Das Geräte- und Lebenszyklusverhalten muss in Ihrer Android-Anwendung getestet werden.

Beispiel

Die Beispiele mit Versions-Tag veranschaulichen die Android-Integration. Wenden Sie die oben genannten Anforderungen an das Signieren im Backend auf jedes Beispiel an, das Sie anpassen; übernehmen Sie keine appseitigen geheimen Zugangsdaten aus älteren Beispielen.

Dokumentation

Die vollständige API-Dokumentation finden Sie in der Javadoc für 0.2.0.