Transloadit

Android SDK

transloadit/android-sdk

Install

This guide uses Android SDK 0.2.0 with Java SDK 2.2.4. The Android package is an AAR, available from Maven Central. Its published POM omits its dependencies. Add the Java SDK explicitly, and include the Android dependencies from the tagged build when integrating the Android listener and persistence APIs. Verify that dependency set in your 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>

Usage

All interactions with the SDK begin with the com.transloadit.android.sdk.AndroidTransloadit class.

Authentication Methods

Keep the Auth Secret on your backend, including for internally distributed apps. APK contents and downloaded configuration cannot keep it confidential. Require Signature Authentication for the Workspace or Template used by the app. The Auth Key can be supplied to the app; the Auth Secret must never be supplied to it.

The key-and-secret constructor is unsuitable for an Android client. Trusted server applications can use the Java SDK with server-held credentials.

Backend Signature Authentication

The SDK calls SignatureProvider.generateSignature synchronously with the exact serialized params it will send. It adds auth, a fresh nonce, and an expiry five minutes in the future with the constructor used below. Your backend must validate that expiry against its own clock. Do not parse and reserialize the string before signing, or reuse a signature for different params.

Before using the helper below, implement its SigningBackend interface using your app’s authenticated HTTPS client. This interface is an application integration boundary, not an SDK service. Send the unchanged paramsJson to your own backend and the current user’s session token in the request’s Authorization header. Use a fixed trusted endpoint, reject redirects, bound the request timeout, and throw on transport errors or any unsuccessful HTTP response. Return the backend’s approved params string and signature as SignedParams; never return the Auth Secret.

The backend must authenticate the session and authorize this user’s upload before signing. Allow only the expected Auth Key, fresh nonce, expiry, and the exact resize Step below; reject additional Steps, arbitrary Templates, fields, or destinations. Apply your upload limits and quota policy on the server. For a server-owned Template, disable allow_steps_override and allow only that Template. Being logged in is not permission to sign arbitrary JSON. Sign the approved original UTF-8 bytes with HMAC-SHA384 and return a sha384: prefix followed by the 96 hexadecimal digits.

Create an Assembly

Save this complete helper as MobileImageUpload.java. It binds each returned signature to the SDK’s exact params and refuses missing sessions, mismatched params, and malformed signatures. The backend still owns authorization; these client checks cannot replace it.

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);
  }
}

Pass your Auth Key, current user session token, and backend implementation to MobileImageUpload.createClient. The token authenticates your own backend request; it is not a Transloadit Auth Secret or Transloadit API token. Refresh an expired session before creating a new client. The SDK constructs auth itself, so the signing callback cannot add auth.max_size or auth.max_number_of_files. If your policy requires those limits, enforce them in a server-owned Template or use backend Assembly creation. The number of files added locally is not a server authorization limit.

Create an AndroidAssembly with client.newAssembly(listener, context), pass it and a readable local image to MobileImageUpload.addImage, then call assembly.saveAsync(). Supply an AndroidAssemblyListener implementing onUploadProgress, onUploadFinished, onAssemblyFinished, onUploadFailed, and onAssemblyStatusUpdateFailed. Upload completion is separate from processing completion. Check the returned response’s status() and hasError() as well as handling exceptions; API errors are not always thrown.

Signing performs synchronous work on the caller’s thread. saveAsync() runs Assembly submission on the SDK’s executor, but direct synchronous SDK calls must run off the UI thread. Listener callbacks use the main thread by default in 0.2.0. Keep the Assembly and listener in a suitable lifecycle owner, avoid retaining a destroyed Activity, and manage cancellation and background work in your app. This helper does not provide WorkManager scheduling or establish upload resumption across process death. Device and lifecycle behavior need testing in your Android application.

Example

The tagged examples illustrate Android integration. Apply the backend signing requirements above to any example you adapt; do not copy app-side secrets from older examples.

Documentation

See Javadoc for 0.2.0 for full API documentation.