/aws-amplify

Storage — Mobile

Prerequisites

Initialize Amplify with Auth and Storage plugins before using this feature:

Flutter — lib/main.dart:

await Amplify.addPlugins([AmplifyAuthCognito(), AmplifyStorageS3()]);
await Amplify.configure(amplifyConfig);

Generate dart outputs: npx ampx sandbox --outputs-format dart --outputs-out-dir lib

Swift (Apple platforms):

try Amplify.add(plugin: AWSCognitoAuthPlugin())
try Amplify.add(plugin: AWSS3StoragePlugin())
try Amplify.configure(with: .amplifyOutputs)

Drag amplify_outputs.json into the Xcode project navigator so it is included in the app bundle.

Android:

Amplify.addPlugin(AWSCognitoAuthPlugin())
Amplify.addPlugin(AWSS3StoragePlugin())
Amplify.configure(AmplifyOutputs(R.raw.amplify_outputs), applicationContext)

Place amplify_outputs.json in app/src/main/res/raw/. Enable core library desugaring for API level < 26.

Backend required: Storage must be defined in amplify/storage/resource.ts using defineStorage — see storage-backend.md.

Flutter

Imports: amplify_flutter + amplify_storage_s3. All paths wrapped with StoragePath.fromString().

Security: Amplify Gen2 enables S3 server-side encryption (SSE-S3) by default. All transfers use HTTPS (TLS in transit). For sensitive data, configure SSE-KMS with a customer-managed key via CDK overrides.

Upload progress — use the onProgress callback parameter:

final op = Amplify.Storage.uploadFile(
  localFile: AWSFile.fromPath('/path/to/file'),
  path: const StoragePath.fromString('public/photos/photo.jpg'),
  onProgress: (p) => print('fraction: ${p.fractionCompleted}'),
);
final result = await op.result;

Use const with StoragePath.fromString() for compile-time constant paths.

Swift (Apple platforms)

Supported: iOS 13+, macOS 12+, tvOS 13+, watchOS 9+, visionOS 1+ (preview).

Uses Amplify.Storage with async/await. Import: Amplify.

Download with progress tracking:

let downloadTask = Amplify.Storage.downloadData(
    path: .fromString("public/example.jpg")
)
Task {
    for await progress in await downloadTask.progress {
        print("Progress: \(progress.fractionCompleted)")
    }
}
let data = try await downloadTask.value

Upload with progress tracking:

let uploadTask = Amplify.Storage.uploadData(
    path: .fromString("public/photo.jpg"),
    data: imageData
)
Task {
    for await progress in await uploadTask.progress {
        print("Progress: \(progress)")
    }
}
let result = try await uploadTask.value

Use SwiftUI's PhotosPicker (from import PhotosUI) to obtain image data, then pass to uploadData.

Android (Kotlin)

Android supports both callback-based and coroutine-based APIs. Import: com.amplifyframework.core.Amplify, com.amplifyframework.storage.StoragePath.

Coroutine example (recommended):

private suspend fun uploadFile() {
    val exampleFile = File(applicationContext.filesDir, "example")
    exampleFile.writeText("Example file contents")
    val upload = Amplify.Storage.uploadFile(
        StoragePath.fromString("public/example"), exampleFile
    )
    try {
        val result = upload.result()
        Log.i("MyAmplifyApp", "Successfully uploaded: ${result.path}")
    } catch (error: StorageException) {
        Log.e("MyAmplifyApp", "Upload failed", error)
    }
}

private suspend fun downloadFile() {
    val download = Amplify.Storage.downloadFile(
        StoragePath.fromString("public/example"), localFile
    )
    try {
        val result = download.result()
        Log.i("MyAmplifyApp", "Successfully downloaded: ${result.file.name}")
    } catch (error: StorageException) {
        Log.e("MyAmplifyApp", "Download failed", error)
    }
}

Callback alternative: all operations also accept onSuccess/onError lambdas — e.g. Amplify.Storage.uploadFile(StoragePath.fromString("public/photo.jpg"), file, { result -> ... }, { error -> ... }).

Permissions

For authenticated user paths, use protected/{entity_id}/ or private/{entity_id}/ — the {entity_id} resolves to the user's Cognito identity ID at runtime.

• Android: Verify INTERNET permission is declared in AndroidManifest.xml (usually present by default). If the app accesses the camera, add CAMERA; for gallery access, add READ_MEDIA_IMAGES (API 33+) or READ_EXTERNAL_STORAGE (older).
• Apple (iOS/macOS): No special permissions for S3 storage operations. If the app accesses the camera, add NSCameraUsageDescription in Info.plist. If the app accesses the photo library, add NSPhotoLibraryUsageDescription.
• Flutter: Follows Android/iOS rules above — add permissions in AndroidManifest.xml and Info.plist respectively.

Pitfalls

• Swift SDK uses getURL (capital URL), not getUrl: Using the wrong casing (lowercase l) causes compile errors. JS/web uses getUrl (lowercase), but Swift uses getURL.
• Wrong file wrapper per platform: Flutter requires AWSFile.fromPath(), Swift uses Data (for uploadData) or a file URL (for uploadFile), Android uses File. Using the wrong type causes compile errors — check the platform's expected input.
• Missing StoragePath.fromString(): Flutter and Android require StoragePath.fromString('path') to wrap path strings. Passing a raw string literal does not compile.
• Large file uploads on mobile: For files over 5 MB, the SDK automatically uses multipart upload. You SHOULD implement progress tracking (onProgress in Flutter, for await progress in ... in Swift, transferObserver or progress callback in Android) to show upload progress to the user.

Links

• Storage Overview (Android)
• Set Up Storage (Android)
• Upload Files (Android)
• Download Files (Android)
• Storage Overview (Swift)
• Set Up Storage (Swift)
• Upload Files (Swift)
• Download Files (Swift)
• Storage Overview (Flutter)
• Set Up Storage (Flutter)
• Upload Files (Flutter)
• Download Files (Flutter)