Transloadit

SDK Android

transloadit/android-sdk

Installer

Ce guide utilise le SDK Android 0.2.1 avec le SDK Java 2.2.4. Le paquet Android est un AAR, disponible sur Maven Central. Son POM déclare les dépendances du SDK Java, de tus et de WorkManager, que Gradle et Maven ajoutent donc automatiquement.

Gradle :

implementation 'com.transloadit.android.sdk:transloadit-android:0.2.1'

Maven :

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

Utilisation

Toutes les interactions avec le SDK commencent par la classe com.transloadit.android.sdk.AndroidTransloadit.

Méthodes d’authentification

Conservez l’Auth Secret sur votre backend, y compris pour les applications distribuées en interne. Le contenu d’un APK et la configuration téléchargée ne peuvent pas en préserver la confidentialité. Exigez la Signature Authentication pour le Workspace ou le Template utilisé par l’application. L’Auth Key peut être fournie à l’application ; l’Auth Secret ne doit jamais lui être fourni.

Le constructeur avec clé et secret ne convient pas à un client Android. Les applications serveur de confiance peuvent utiliser le SDK Java avec des identifiants détenus par le serveur.

Signature Authentication côté backend

Le SDK appelle SignatureProvider.generateSignature de manière synchrone avec la valeur params sérialisée exacte qu’il enverra. Il ajoute auth, un nouveau nonce et une expiration fixée à cinq minutes dans le futur avec le constructeur utilisé ci-dessous. Votre backend doit valider cette expiration par rapport à sa propre horloge. Avant la signature, n’analysez pas la chaîne pour la resérialiser, et ne réutilisez pas une signature pour d’autres paramètres.

Avant d’utiliser l’assistant ci-dessous, implémentez son interface SigningBackend à l’aide du client HTTPS authentifié de votre application. Cette interface est une frontière d’intégration applicative, et non un service du SDK. Envoyez la valeur paramsJson inchangée à votre propre backend, ainsi que le jeton de session de l’utilisateur actuel dans l’en-tête Authorization de la requête. Utilisez un point de terminaison fixe et de confiance, refusez les redirections, limitez le délai d’expiration de la requête et levez une exception en cas d’erreur de transport ou de réponse HTTP en échec. Retournez la chaîne de paramètres approuvée par le backend et la signature sous forme de SignedParams ; ne retournez jamais l’Auth Secret.

Le backend doit authentifier la session et autoriser l’envoi de cet utilisateur avant de signer. N’autorisez que l’Auth Key attendue, un nonce récent, l’expiration et exactement le Step de redimensionnement ci-dessous ; refusez tout Step supplémentaire ainsi que les Templates, champs ou destinations arbitraires. Appliquez vos limites d’envoi et votre politique de quota côté serveur. Pour un Template détenu par le serveur, désactivez allow_steps_override et n’autorisez que ce Template. Être connecté ne donne pas la permission de signer du JSON arbitraire. Signez les octets UTF-8 originaux approuvés avec HMAC-SHA384 et retournez un préfixe sha384: suivi des 96 chiffres hexadécimaux.

Créer une Assembly

Enregistrez cet assistant complet sous MobileImageUpload.java. Il lie chaque signature retournée aux paramètres exacts du SDK et refuse les sessions manquantes, les paramètres non concordants et les signatures mal formées. Le backend reste responsable de l’autorisation ; ces vérifications côté client ne peuvent pas la remplacer.

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

Passez votre Auth Key, le jeton de session de l’utilisateur actuel et l’implémentation de votre backend à MobileImageUpload.createClient. Ce jeton authentifie la requête vers votre propre backend ; il ne s’agit ni d’un Auth Secret Transloadit ni d’un jeton d’API Transloadit. Actualisez une session expirée avant de créer un nouveau client. Le SDK construit lui-même auth, si bien que le callback de signature ne peut pas ajouter auth.max_size ni auth.max_number_of_files. Si votre politique exige ces limites, appliquez-les dans un Template détenu par le serveur ou créez l’Assembly depuis le backend. Le nombre de fichiers ajoutés localement n’est pas une limite d’autorisation côté serveur.

Créez un objet AndroidAssembly avec client.newAssembly(listener, context), passez-le et une image locale lisible à MobileImageUpload.addImage, puis appelez assembly.saveAsync(). Fournissez un AndroidAssemblyListener implémentant onUploadProgress, onUploadFinished, onAssemblyFinished, onUploadFailed et onAssemblyStatusUpdateFailed. La fin de l’envoi est distincte de la fin du traitement. Vérifiez les valeurs status() et hasError() de la réponse obtenue, en plus de gérer les exceptions ; les erreurs d’API ne sont pas toujours levées.

La signature effectue un travail synchrone sur le thread de l’appelant. saveAsync() exécute la soumission de l’Assembly sur l’exécuteur du SDK, mais les appels synchrones directs au SDK doivent s’exécuter hors du thread d’interface. Les callbacks de l’écouteur utilisent le thread principal par défaut. Conservez l’Assembly et l’écouteur dans un propriétaire de cycle de vie adapté, évitez de retenir une Activity détruite et gérez l’annulation et le travail en arrière-plan dans votre application. Le SDK prend également en charge les envois en arrière-plan via WorkManager, comme illustré ci-dessous. Le comportement selon l’appareil et le cycle de vie doit être testé dans votre application Android.

Envois en arrière-plan avec WorkManager

Utilisez AndroidAssemblyWorkConfig pour mettre en file d’attente un AndroidAssemblyUploadWorker via WorkManager. Le worker utilise tus et SharedPreferences pour les envois reprenables. Gardez le fichier local disponible jusqu’à la fin de la tâche.

WorkManager conserve les en-têtes de signature dans les données de la tâche. Utilisez un uploadToken émis par votre backend, limité à cet envoi et valide pendant toute la durée de vie planifiée de la tâche. S’il expire ou est refusé, le worker fait échouer la tâche ; mettez alors en file d’attente une nouvelle requête avec de nouveaux identifiants. L’actualisation de la session de l’application ne met pas à jour les identifiants des tâches en file d’attente.

Le worker envoie les paramètres sérialisés du SDK comme corps UTF-8 d’une requête POST application/json. Configurez un point de terminaison de signature HTTPS fixe qui répond directement, sans redirection. Appliquez la politique d’autorisation du backend décrite ci-dessus, signez le corps de requête inchangé et retournez un objet JSON contenant un champ signature.

Utilisez un Template détenu par le serveur contenant les Steps de redimensionnement approuvés. Votre backend doit autoriser exactement ce Template et cette URL de notification. Le SDK ajoute auth lorsque le worker soumet l’Assembly. Créez paramsJson avec les options approuvées :

import androidx.work.WorkManager;
import com.transloadit.android.sdk.AndroidAssemblyWorkConfig;

String paramsJson = "{\"template_id\":\"YOUR_APPROVED_TEMPLATE_ID\","
    + "\"notify_url\":\"https://your-backend.example/transloadit-notify\"}";

AndroidAssemblyWorkConfig config = AndroidAssemblyWorkConfig
    .newBuilder(authKey)
    .signatureProvider("https://your-backend.example/sign")
    .addSignatureProviderHeader("Authorization", "Bearer " + uploadToken)
    .paramsJson(paramsJson)
    .preferenceName("image_uploads")
    .addFile(image, "image")
    .waitForCompletion(false)
    .build();

WorkManager.getInstance(context).enqueue(config.toWorkRequest());

Avec waitForCompletion(true), la tâche attend que l’Assembly se termine. Le SDK lit directement l’URL de statut de l’Assembly, si bien que votre backend n’a qu’à signer la création de l’Assembly. Avec waitForCompletion(false), comme dans cet exemple, la tâche se termine après l’envoi ; suivez le traitement sur votre backend à l’aide des Assembly Notifications, avec un notify_url approuvé dans vos paramètres.

Exemple

Les exemples étiquetés illustrent l’intégration Android. Appliquez les exigences de signature côté backend décrites ci-dessus à tout exemple que vous adaptez ; ne copiez pas les secrets côté application des anciens exemples.

Documentation

Consultez la Javadoc pour la documentation complète de l’API.