Transloadit の Flutter SDK ベータ:クロスプラットフォームアプリ対応
2022年9月、クロスプラットフォーム開発フレームワーク Flutter 向けの Transloadit SDK を迎えました。バージョン 0.2.0 は、Transloadit API 操作と、tus プロトコルによる再開可能なファイルアップロードのラッパーを提供していました。ベータ版として公開し、テストとバグ報告を呼びかけましたが、本番環境で使える段階とは考えていませんでした。
パッケージは pub.dev に掲載されています。

セキュリティに関する更新、2026年9月: 元のサンプルでは、Auth Secret を Flutter クライアント内に配置していました。このシークレットをモバイル、デスクトップ、Web アプリに含めて配布したり、リモート設定からアプリ内に取得したりしないでください。実行可能なチュートリアルは、以下の当時のワークフローとパッケージ固有の制限の説明に置き換えました。シークレットは信頼できるバックエンドで保持する必要があります。アプリ内で偽装しても、秘密にはできません。
インストール
ここで取り上げるリリースは 0.2.0 です。この更新時点で、パッケージレジストリに掲載されている最新の公開バージョンは
0.2.1 です。以前この記事の依存関係の例に記載されていた
1.0.0 リリースは存在しません。公開済みの 0.2.1 パッケージには、Dart SDK の制約
>=2.12.0 <3.0.0 と Flutter SDK への依存関係が宣言されています。Dart 3 を使用するプロジェクトには、そのまま追加できません。
ライブラリのインポートパスは package:transloadit/transloadit.dart です。これらは当時のパッケージを特定するための情報であり、現在の Flutter プロジェクトのダウングレードを推奨するものではありません。既存の連携を調査する際は、公開パッケージのメタデータを参照してください。
SDK の使用
公開されているクライアントクラスは、元のサンプルで使用していた
Transloadit ではなく、TransloaditClient です。このクライアントは、Assembly の作成、ステータスの取得、Template の管理などの操作をまとめており、呼び出し側で各 HTTP リクエストを手作業で組み立てる必要がありません。
ただし、0.2.1 コンストラクターには
authSecret が必須で、リクエストの実装はローカルでパラメーターに署名します。サーバーで生成した署名を受け取る公開コールバックはありません。コンストラクターからシークレットを削除する、空文字列を渡す、バックエンドの URL を追加するといった変更だけでは、このパッケージをモバイル向けの安全な署名連携に変えることはできません。この制限は、発表で紹介した 0.2.0 のワークフローにも当てはまります。
本番環境での連携には、別のリクエスト経路が必要です。バックエンドでユーザーを認証し、アップロードを認可するとともに、処理設定、保存先、制限、有効期限を制御する必要があります。バックエンド自体で Assembly を作成するか、承認済みで有効期間の短いパラメーターと署名を、それらを変更せずに送信できるクライアントに提供します。このプロトコルについては、Signature Authentication ガイドと Assembly 作成 APIを参照してください。これはアーキテクチャ上の代替案であり、この Flutter パッケージが提供する機能ではありません。
Assembly の作成
元のチュートリアルでは、ローカル画像の幅を 400 ピクセルに変更していました。その手順は、SDK の構成を理解するうえでは今も役立ちます。
- クライアントの
newAssemblyメソッドを呼び出して、TransloaditAssemblyを取得します。これは、リクエストの送信前にファイルと Step を集めます。 addFileでサンプル画像cat.jpgを添付します。公開済みパッケージはFileを受け取り、そのパスを tus クライアント用のXFileでラップします。resizeという名前の Step を追加し、Robot/image/resizeを使用して、widthを 400 に設定します。これは画像の処理設定であり、画像のバイト転送とは別のものです。createAssemblyで送信します。パッケージはまず Assembly を作成し、その tus アップロード URL を使ってファイルを転送します。- 転送の進捗には
onProgress、ファイルのアップロード完了にはonCompleteを使用します。このワークフローでは、アップロードの完了と処理の完了は別です。アップロードのコールバックだけでは、サイズ変更後の画像が準備できたとは判断できません。 - 返された
TransloaditResponseは、レスポンスオブジェクト自体をインデックスで参照するのではなく、response.data['ok']を通じて読み取ります。ASSEMBLY_COMPLETEDは処理の成功を示します。パッケージはキャンセルまたは中止された Assembly を返すこともあり、エラーには別途対処する必要があります。
これらの API の詳細は、安全でないクライアント側の署名経路を現在のアップロード手順として提示せずに、ベータ版のワークフローを説明するものです。代替実装でも、認可とシークレットをバックエンドに保持しながら、転送の進捗と処理結果を明確に区別する必要があります。
次のステップは?
元の発表では、より大きなサンプルとして Flutter のレシピアプリシリーズを紹介していました。その当時のチュートリアルもリモート設定を通じて認証情報を配布していたため、安全な実装ガイドとして従うべきではありません。新しい連携を設計する際は、上記の認証と Assembly のリファレンスから確認してください。
ベータ版の実装履歴と課題トラッカーは、Flutter SDK リポジトリを参照してください。引き続き貢献を歓迎しています。ただし、認可済みのサーバー生成パラメーターを受け取るクライアント連携をここで推奨するには、その実装と検証が別途必要です。
