Android SDK
インストール
このガイドでは、Android SDK 0.2.1 と
Java SDK 2.2.4 を使用します。Android パッケージは AAR 形式で、Maven Central から入手できます。POM に Java SDK、tus、WorkManager の依存関係が宣言されているため、Gradle と Maven が自動で追加します。
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>
使用方法
SDK の操作はすべて com.transloadit.android.sdk.AndroidTransloadit クラスから始まります。
認証方法
社内配布のアプリも含め、Auth Secretはバックエンドで保持してください。APK の内容やダウンロードした設定では機密性を保てません。アプリが使用する Workspace または Template では、Signature Authentication を必須にしてください。Auth Key はアプリに渡せますが、Auth Secret は絶対に渡さないでください。
キーとシークレットを受け取るコンストラクターは、Android クライアントには適していません。信頼できるサーバーアプリケーションでは、サーバーで保持する認証情報を使って Java SDK を利用できます。
バックエンドでの Signature Authentication
SDK は、送信するものと完全に同じシリアライズ済みの
params を渡して、SignatureProvider.generateSignature を同期的に呼び出します。以下のコンストラクターを使うと、auth、新しい nonce、5 分後の有効期限が追加されます。バックエンドでは、自身の時計を基準にその有効期限を検証する必要があります。署名前に文字列を解析して再シリアライズしたり、異なる params に署名を再利用したりしないでください。
以下のヘルパーを使う前に、アプリの認証済み HTTPS クライアントを使って、ヘルパーの SigningBackend インターフェースを実装してください。これはアプリケーションとの統合境界を定めるインターフェースであり、SDK のサービスではありません。変更していない paramsJson を独自のバックエンドに送り、リクエストの Authorization ヘッダーには現在のユーザーのセッショントークンを指定します。信頼できる固定エンドポイントを使い、リダイレクトを拒否し、リクエストのタイムアウトに上限を設け、通信エラーや成功以外の HTTP レスポンスでは例外をスローしてください。バックエンドが承認した params 文字列と署名を SignedParams として返します。Auth Secret は絶対に返さないでください。
バックエンドでは、署名前にセッションを認証し、そのユーザーのアップロードを認可する必要があります。想定する Auth Key、新しい nonce、有効期限、以下と完全に一致するリサイズ用 Step のみを許可し、追加の Step、任意の Template、フィールド、送信先は拒否してください。アップロード制限とクォータのポリシーはサーバーで適用します。サーバーが管理する Template を使う場合は、allow_steps_override を無効にし、その Template のみを許可してください。ログイン済みであることは、任意の JSON への署名を許可する理由にはなりません。承認した元の UTF-8 バイト列に HMAC-SHA384 で署名し、sha384: というプレフィックスに続けて 96 桁の16進数を返してください。
Assembly の作成
このヘルパー全体を MobileImageUpload.java として保存してください。返された各署名を SDK の正確な params に結び付け、セッションの欠落、params の不一致、形式が不正な署名を拒否します。認可の責任は引き続きバックエンドにあり、これらのクライアント側の検証で代替することはできません。
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);
}
}
Auth Key、現在のユーザーのセッショントークン、バックエンドの実装を
MobileImageUpload.createClient に渡してください。このトークンは独自のバックエンドへのリクエストを認証するもので、Transloadit の Auth Secret や Transloadit API トークンではありません。セッションの期限が切れている場合は、新しいクライアントを作成する前に更新してください。SDK 自体が auth を構築するため、署名コールバックでは
auth.max_size や auth.max_number_of_files を追加できません。ポリシーでこれらの制限が必要な場合は、サーバーが管理する Template で適用するか、バックエンドで Assembly を作成してください。ローカルで追加するファイル数は、サーバー側の認可制限にはなりません。
client.newAssembly(listener, context) で AndroidAssembly を作成し、読み取り可能なローカル画像とともに MobileImageUpload.addImage に渡してから、assembly.saveAsync() を呼び出してください。onUploadProgress、onUploadFinished、onAssemblyFinished、onUploadFailed、onAssemblyStatusUpdateFailed を実装する AndroidAssemblyListener を指定します。アップロードの完了と処理の完了は別です。例外処理に加えて、返されたレスポンスの
status() と hasError() も確認してください。API エラーが必ず例外としてスローされるとは限りません。
署名処理は呼び出し元のスレッドで同期的に実行されます。saveAsync() は SDK のエグゼキューターで Assembly を送信しますが、SDK を直接同期呼び出しする場合は、UI スレッド以外で実行する必要があります。リスナーのコールバックは、デフォルトではメインスレッドを使用します。Assembly とリスナーを適切なライフサイクルオーナーで保持し、破棄された Activity の保持を避け、キャンセルとバックグラウンド処理をアプリで管理してください。SDK は、以下に示す WorkManager を使ったバックグラウンドアップロードにも対応しています。デバイスやライフサイクルに関する動作は、実際の Android アプリケーションでテストする必要があります。
WorkManager によるバックグラウンドアップロード
AndroidAssemblyWorkConfig を使い、WorkManager 経由で
AndroidAssemblyUploadWorker をキューに追加します。ワーカーは tus と SharedPreferences を使って再開可能なアップロードを行います。ジョブが完了するまで、ローカルファイルを利用可能な状態に保ってください。
WorkManager は署名用ヘッダーをジョブデータに永続化します。バックエンドが発行し、このアップロードだけを対象とし、ジョブの予定存続期間中に有効な
uploadToken を使用してください。期限切れまたは拒否された場合、ワーカーはジョブを失敗として終了します。新しい認証情報で新たなリクエストをキューに追加してください。アプリのセッションを更新しても、キュー内のジョブの認証情報は更新されません。
ワーカーは、SDK がシリアライズした params を
application/json POST の UTF-8 本文として送信します。リダイレクトせずに直接応答する、固定の HTTPS 署名エンドポイントを設定してください。前述のバックエンド認可ポリシーを適用し、変更していないリクエスト本文に署名して、signature フィールドを含む JSON オブジェクトを返します。
承認済みのリサイズ用 Step を含む、サーバー管理の Template を使用してください。バックエンドでは、その正確な Template と通知 URL を許可する必要があります。ワーカーが Assembly を送信するとき、SDK は auth を追加します。承認済みのオプションで paramsJson を作成してください。
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());
waitForCompletion(true) の場合、ジョブは Assembly が完了するまで待機します。SDK が Assembly のステータス URL を直接読み取るため、バックエンドは Assembly 作成への署名だけを行います。この例のように waitForCompletion(false) の場合、アップロード後にジョブが終了します。params に承認済みの notify_url を指定し、Assembly Notification を使ってバックエンドで処理状況を追跡してください。
使用例
タグ付きのサンプルで Android への統合方法を確認できます。サンプルを応用する際は、いずれの場合も前述のバックエンド署名の要件を適用してください。古いサンプルにあるアプリ側のシークレットをコピーしないでください。
ドキュメント
API ドキュメントの全容は、Javadoc を参照してください。