Transloadit

SDK para Android

transloadit/android-sdk

Instalar

Este guia usa o SDK para Android 0.2.0 com o SDK para Java 2.2.4. O pacote Android é um AAR, disponível no Maven Central. O POM publicado omite as dependências do pacote. Adicione o SDK para Java explicitamente e inclua as dependências do Android do build da tag ao integrar as APIs de listener e persistência do Android. Verifique esse conjunto de dependências no seu 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>

Uso

Todas as interações com o SDK começam com a classe com.transloadit.android.sdk.AndroidTransloadit.

Métodos de autenticação

Mantenha o Auth Secret no seu backend, inclusive em apps distribuídos internamente. O conteúdo do APK e a configuração baixada não podem mantê-lo confidencial. Exija Signature Authentication para o Workspace ou Template usado pelo app. A Auth Key pode ser fornecida ao app; o Auth Secret nunca deve ser fornecido a ele.

O construtor com chave e segredo não é adequado para um cliente Android. Aplicações de servidor confiáveis podem usar o SDK para Java com credenciais mantidas no servidor.

Signature Authentication no backend

O SDK chama SignatureProvider.generateSignature de forma síncrona, usando exatamente o params serializado que enviará. Com o construtor usado abaixo, ele adiciona auth, um novo nonce e uma expiração em cinco minutos. Seu backend deve validar essa expiração com base no próprio relógio. Não faça o parsing e a serialização da string novamente antes de assinar, nem reutilize uma assinatura para parâmetros diferentes.

Antes de usar o código auxiliar abaixo, implemente sua interface SigningBackend usando o cliente HTTPS autenticado do seu app. Essa interface é um ponto de integração da aplicação, não um serviço do SDK. Envie o paramsJson sem alterações ao seu próprio backend e inclua o token de sessão do usuário atual no cabeçalho Authorization da requisição. Use um endpoint fixo e confiável, rejeite redirecionamentos, limite o tempo de espera da requisição e lance uma exceção em caso de erros de transporte ou de qualquer resposta HTTP sem sucesso. Retorne a string de parâmetros aprovada pelo backend e a assinatura como SignedParams; nunca retorne o Auth Secret.

O backend deve autenticar a sessão e autorizar o upload desse usuário antes de assinar. Permita apenas a Auth Key esperada, um nonce novo, a expiração e exatamente o Step de redimensionamento abaixo; rejeite Steps adicionais, Templates arbitrários, campos ou destinos. Aplique seus limites de upload e sua política de cotas no servidor. Para um Template controlado pelo servidor, desative allow_steps_override e permita apenas esse Template. Estar autenticado não dá permissão para assinar JSON arbitrário. Assine os bytes UTF-8 originais aprovados com HMAC-SHA384 e retorne um prefixo sha384: seguido dos 96 dígitos hexadecimais.

Criar uma Assembly

Salve este código auxiliar completo como MobileImageUpload.java. Ele vincula cada assinatura retornada aos parâmetros exatos do SDK e rejeita sessões ausentes, parâmetros divergentes e assinaturas malformadas. O backend continua responsável pela autorização; essas verificações no cliente não podem substituí-la.

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

Passe sua Auth Key, o token de sessão do usuário atual e a implementação do backend para MobileImageUpload.createClient. O token autentica a requisição ao seu próprio backend; ele não é um Auth Secret da Transloadit nem um token da API da Transloadit. Renove uma sessão expirada antes de criar um novo cliente. O próprio SDK constrói auth, então o callback de assinatura não pode adicionar auth.max_size ou auth.max_number_of_files. Se sua política exigir esses limites, aplique-os em um Template controlado pelo servidor ou crie a Assembly no backend. O número de arquivos adicionados localmente não é um limite de autorização no servidor.

Crie um AndroidAssembly com client.newAssembly(listener, context), passe-o junto com uma imagem local que possa ser lida para MobileImageUpload.addImage e chame assembly.saveAsync(). Forneça um AndroidAssemblyListener que implemente onUploadProgress, onUploadFinished, onAssemblyFinished, onUploadFailed e onAssemblyStatusUpdateFailed. A conclusão do upload é distinta da conclusão do processamento. Verifique status() e hasError() na resposta retornada, além de tratar exceções; erros da API nem sempre geram exceções.

A assinatura é realizada de forma síncrona na thread que faz a chamada. saveAsync() executa o envio da Assembly no executor do SDK, mas chamadas síncronas diretas ao SDK devem ser executadas fora da thread da UI. Por padrão, os callbacks do listener usam a thread principal em 0.2.0. Mantenha a Assembly e o listener em um componente adequado responsável pelo ciclo de vida, evite manter uma referência a uma Activity destruída e gerencie o cancelamento e o trabalho em segundo plano no seu app. Este código auxiliar não oferece agendamento com o WorkManager nem implementa a retomada de uploads após o encerramento do processo. É necessário testar o comportamento relacionado ao dispositivo e ao ciclo de vida no seu app Android.

Exemplo

Os exemplos da tag ilustram a integração com o Android. Aplique os requisitos de assinatura no backend descritos acima a qualquer exemplo que você adaptar; não copie segredos incluídos no app em exemplos antigos.

Documentação

Consulte o Javadoc da versão 0.2.0 para ver a documentação completa da API.