SDK Android
Installer
Ce guide utilise le SDK Android 0.2.0 avec le SDK Java
2.2.4. Le paquet Android est un AAR,
disponible sur Maven Central.
Le POM publié ne déclare pas ses dépendances. Ajoutez explicitement le SDK Java et incluez les
dépendances Android du build associé au tag
lorsque vous intégrez les API Android d’écouteurs et de persistance. Vérifiez cet ensemble de
dépendances dans votre application.
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>
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. Ni le contenu des APK ni la configuration téléchargée ne peuvent préserver sa confidentialité. Exigez 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 acceptant une clé et un secret ne convient pas à un client Android. Les applications serveur de confiance peuvent utiliser le SDK Java avec des données d’accès conservées côté serveur.
Signature Authentication côté backend
Le SDK appelle SignatureProvider.generateSignature de manière synchrone avec la valeur sérialisée exacte
params qu’il enverra. Avec le constructeur utilisé ci-dessous, il ajoute
auth, une nouvelle valeur nonce et une date
d’expiration fixée à cinq minutes plus tard. Votre backend doit valider cette date d’expiration
par rapport à sa propre horloge. N’analysez pas la chaîne pour la resérialiser avant de la signer,
et ne réutilisez pas une signature pour des paramètres différents.
Avant d’utiliser l’utilitaire ci-dessous, implémentez son interface SigningBackend
à l’aide du client HTTPS authentifié de votre application. Cette interface constitue une frontière
d’intégration avec l’application, et non un service du SDK. Envoyez paramsJson
sans modification à votre propre backend et transmettez 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, rejetez les redirections, limitez le délai d’attente de la requête et levez une exception
en cas d’erreur de transport ou de toute réponse HTTP indiquant un échec. Renvoyez la chaîne de
paramètres approuvée par le backend et la signature sous forme de SignedParams ;
ne renvoyez jamais l’Auth Secret.
Le backend doit authentifier la session et autoriser le téléversement de cet utilisateur avant de
signer. N’autorisez que l’Auth Key attendue, un nouveau nonce, la date d’expiration et le Step de
redimensionnement exact présenté ci-dessous ; rejetez les Steps supplémentaires ainsi que les
Templates, champs ou destinations arbitraires. Appliquez vos limites de téléversement et votre politique
de quotas sur le serveur. Pour un Template sous le contrôle du serveur, désactivez
allow_steps_override et n’autorisez que ce Template. Le fait d’être connecté ne donne pas
l’autorisation de signer du JSON arbitraire. Signez les octets UTF-8 d’origine approuvés avec
HMAC-SHA384 et renvoyez un préfixe sha384: suivi des 96 chiffres hexadécimaux.
Créer une Assembly
Enregistrez cet utilitaire complet sous le nom MobileImageUpload.java. Il lie chaque signature
renvoyée aux paramètres exacts du SDK et refuse les sessions manquantes, les paramètres qui ne
correspondent pas et les signatures mal formées. L’autorisation reste de la responsabilité du
backend ; 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);
}
}
Transmettez votre Auth Key, le jeton de session de l’utilisateur actuel et votre implémentation du
backend à MobileImageUpload.createClient. Le jeton authentifie la requête adressée à votre propre
backend ; ce n’est ni un Auth Secret Transloadit ni un jeton de l’API Transloadit. Renouvelez une
session expirée avant de créer un nouveau client. Le SDK construit lui-même
auth ; la fonction de rappel de signature ne peut donc pas ajouter
auth.max_size ni auth.max_number_of_files. Si votre politique exige ces limites,
imposez-les dans un Template sous le contrôle du serveur ou recourez à la création d’Assemblies côté
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), transmettez-le avec
une image locale accessible en lecture à MobileImageUpload.addImage, puis appelez
assembly.saveAsync(). Fournissez un objet AndroidAssemblyListener qui implémente
onUploadProgress, onUploadFinished, onAssemblyFinished,
onUploadFailed et onAssemblyStatusUpdateFailed. La fin du téléversement est distincte
de la fin du traitement. Vérifiez les valeurs status() et
hasError() de la réponse renvoyée et gérez aussi les exceptions ; les erreurs de
l’API ne sont pas toujours levées sous forme d’exceptions.
L’opération de signature s’exécute de manière synchrone sur le thread 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 de l’interface utilisateur. Les
fonctions de rappel de l’écouteur utilisent le thread principal par défaut dans
0.2.0. Conservez l’Assembly et l’écouteur dans un propriétaire de cycle de
vie adapté, évitez de conserver une référence à une Activity détruite et gérez l’annulation et le
travail en arrière-plan dans votre application. Cet utilitaire ne fournit pas de planification via
WorkManager et ne met pas en place la reprise des téléversements après l’arrêt du processus. Le
comportement sur les appareils et au cours du cycle de vie doit être testé dans votre application
Android.
Exemple
Les exemples associés au tag illustrent l’intégration Android. Appliquez les exigences de signature côté backend ci-dessus à tout exemple que vous adaptez ; ne copiez pas les secrets côté application provenant d’anciens exemples.
Documentation
Consultez la Javadoc de la version 0.2.0 pour la documentation complète de l’API.