Transloadit

SDK para Android

transloadit/android-sdk

Instalación

Esta guía usa el SDK para Android 0.2.0 con el SDK de Java 2.2.4. El paquete para Android es un AAR, disponible en Maven Central. Su POM publicado omite las dependencias. Añade explícitamente el SDK de Java e incluye las dependencias de Android de la compilación etiquetada al integrar las API de listeners y persistencia de Android. Verifica ese conjunto de dependencias en tu aplicación.

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>

Uso

Todas las interacciones con el SDK comienzan con la clase com.transloadit.android.sdk.AndroidTransloadit.

Métodos de autenticación

Mantén el Auth Secret en tu backend, incluso para aplicaciones distribuidas internamente. El contenido del APK y la configuración descargada no pueden mantenerlo confidencial. Exige Signature Authentication para el Workspace o Template que usa la aplicación. Puedes proporcionar la Auth Key a la aplicación; nunca debes proporcionarle el Auth Secret.

El constructor con clave y secreto no es adecuado para un cliente Android. Las aplicaciones de servidor de confianza pueden usar el SDK de Java con credenciales almacenadas en el servidor.

Signature Authentication en el backend

El SDK llama a SignatureProvider.generateSignature de forma síncrona con el valor serializado exacto de params que enviará. Con el constructor que se usa a continuación, el SDK añade auth, un nuevo nonce y un vencimiento dentro de cinco minutos. Tu backend debe validar ese vencimiento con su propio reloj. No analices ni vuelvas a serializar la cadena antes de firmarla, ni reutilices una firma para parámetros diferentes.

Antes de usar la clase auxiliar que se muestra a continuación, implementa su interfaz SigningBackend con el cliente HTTPS autenticado de tu aplicación. Esta interfaz delimita la integración con la aplicación; no es un servicio del SDK. Envía paramsJson sin modificar a tu propio backend y el token de sesión del usuario actual en el encabezado Authorization de la solicitud. Usa un endpoint fijo y de confianza, rechaza las redirecciones, limita el tiempo de espera de la solicitud y lanza una excepción ante errores de transporte o cualquier respuesta HTTP que no sea exitosa. Devuelve la cadena de parámetros aprobada por el backend y la firma como SignedParams; nunca devuelvas el Auth Secret.

El backend debe autenticar la sesión y autorizar la subida de este usuario antes de firmar. Permite únicamente la Auth Key esperada, un nonce nuevo, el vencimiento y el Step exacto de cambio de tamaño que se muestra a continuación; rechaza Steps adicionales, Templates arbitrarios, campos o destinos. Aplica tus límites de subida y tu política de cuotas en el servidor. Para un Template controlado por el servidor, desactiva allow_steps_override y permite únicamente ese Template. Haber iniciado sesión no otorga permiso para firmar JSON arbitrario. Firma los bytes UTF-8 originales aprobados con HMAC-SHA384 y devuelve un prefijo sha384: seguido de los 96 dígitos hexadecimales.

Crear una Assembly

Guarda esta clase auxiliar completa como MobileImageUpload.java. La clase auxiliar vincula cada firma recibida con los parámetros exactos del SDK y rechaza la ausencia de sesión, los parámetros que no coincidan y las firmas con formato incorrecto. La autorización sigue siendo responsabilidad del backend; estas comprobaciones del cliente no pueden sustituirla.

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

Pasa tu Auth Key, el token de sesión del usuario actual y tu implementación del backend a MobileImageUpload.createClient. El token autentica la solicitud a tu propio backend; no es un Auth Secret de Transloadit ni un token de la API de Transloadit. Renueva una sesión vencida antes de crear un nuevo cliente. El propio SDK construye auth, por lo que el callback de firma no puede añadir auth.max_size ni auth.max_number_of_files. Si tu política exige esos límites, aplícalos en un Template controlado por el servidor o crea las Assemblies desde el backend. La cantidad de archivos añadidos localmente no constituye un límite de autorización del servidor.

Crea un AndroidAssembly con client.newAssembly(listener, context), pásalo junto con una imagen local que se pueda leer a MobileImageUpload.addImage y luego llama a assembly.saveAsync(). Proporciona un AndroidAssemblyListener que implemente onUploadProgress, onUploadFinished, onAssemblyFinished, onUploadFailed y onAssemblyStatusUpdateFailed. La finalización de la subida es independiente de la finalización del procesamiento. Comprueba status() y hasError() en la respuesta recibida, además de gestionar las excepciones; los errores de la API no siempre se lanzan como excepciones.

La firma realiza trabajo síncrono en el hilo que hace la llamada. saveAsync() ejecuta el envío de la Assembly en el ejecutor del SDK, pero las llamadas síncronas directas al SDK deben ejecutarse fuera del hilo de la interfaz de usuario. Los callbacks del listener usan el hilo principal de forma predeterminada en 0.2.0. Mantén la Assembly y el listener en un propietario de ciclo de vida adecuado, evita retener una Activity destruida y gestiona la cancelación y el trabajo en segundo plano en tu aplicación. Esta clase auxiliar no proporciona programación de tareas con WorkManager ni permite reanudar las subidas tras la terminación del proceso. Debes probar el comportamiento del dispositivo y del ciclo de vida en tu aplicación Android.

Ejemplo

Los ejemplos etiquetados ilustran la integración con Android. Aplica los requisitos de firma en el backend descritos arriba a cualquier ejemplo que adaptes; no copies secretos del lado de la aplicación de ejemplos antiguos.

Documentación

Consulta Javadoc para 0.2.0 para ver la documentación completa de la API.