Getting started

You are currently viewing the AWS SDK for Mobile documentation which is a collection of low-level libraries. Use the Amplify libraries for all new app development. Learn more

Enable your app to store and retrieve user files from cloud storage with the permissions model that suits your purpose. The CLI deploys and configures cloud storage buckets using Amazon Simple Storage Service (Amazon S3).

Note

This guide specifically uses TransferUtility, which is a high-level wrapper over AmazonS3Client. TransferUtility is a tool that simplifies asynchronous transfer management (i.e. upload and download), and it may not contain all of the features available in Amazon S3 service. To access low-level features such as bucket manipulation and object deletion, please refer to the documentation for AmazonS3Client.

Storage Access

The CLI configures three different access levels on the storage bucket: public, protected and private. When you run amplify add storage, the CLI will configure appropriate IAM policies on the bucket using a Cognito Identity Pool Role. You will have the option of adding CRUD (Create/Update, Read and Delete) based permissions as well, so that Authenticated and Guest users will be granted limited permissions within these levels.

If you had previously enabled user sign-in by running amplify add auth in your project, the policies will be connected to an Authenticated Role of the Identity Pool which has scoped permission to the objects in the bucket for each user identity. If you haven't configured user sign-in, then an Unauthenticated Role will be assigned for each unique user/device combination, which still has scoped permissions to just their objects.

Public: Accessible by all users of your app. Files are stored under the public/ path in your S3 bucket.
Protected: Readable by all users, but writable only by the creating user. Files are stored under protected/{user_identity_id}/ where the user_identity_id corresponds to the unique Amazon Cognito Identity ID for that user.
Private: Only accessible for the individual user. Files are stored under private/{user_identity_id}/ where the user_identity_id corresponds to the unique Amazon Cognito Identity ID for that user.

See Authentication for more information on how to get the user_identity_id for a signed in user.

Set Up Your Backend

Complete the Get Started steps before you proceed.
Use the CLI to add storage to your cloud-enabled backend and app.

In a terminal window, navigate to your project folder (the folder that typically contains your project level build.gradle), and add the SDK to your app.
```
cd YOUR_PROJECT_FOLDER
amplify add storage
```

Choose Content as your storage service.

❯ Content (Images, audio, video, etc.)

The combination of friendly name and bucket name must be globally unique. If another S3 user has specified the same values for both of these as you, the amplify push step below will fail.
The CLI walks you through the options to enable Auth (if not enabled previously), to name your S3 bucket, and to decide who should have access (select Auth and guest users and toggle all to select create/update, read, and delete access for both auth and guest users).

Confirm that you have Storage and Auth set up.

$ amplify status
  | Category  | Resource name   | Operation | Provider plugin   |
  | --------- | --------------- | --------- | ----------------- |
  | Auth      | cognito2e202b09 | Create    | awscloudformation |
  | Storage   | sabc0123de      | Create    | awscloudformation |

To create your backend run:
```
amplify push
```
The CLI will create the awsconfiguration.json file in your project's res/raw directory.

Lambda Triggers

If you want to enable triggers for the storage category with Amazon S3 & Amazon DynamoDB as providers, the CLI supports associating Lambda triggers with S3 and DynamoDB events. For example, this can be useful for a use case where you want to invoke a Lambda function after a create or update operation on a DynamoDB table managed by the Amplify CLI. Read More

Connect to Your Backend

Use the following steps to connect add file storage backend services to your app.

Add the following to app/build.gradle (Module:app):

dependencies {
  implementation 'com.amazonaws:aws-android-sdk-s3:ANDROID_SDK_VERSION'
  implementation 'com.amazonaws:aws-android-sdk-mobile-client:ANDROID_SDK_VERSION'
  implementation 'com.amazonaws:aws-android-sdk-auth-userpools:ANDROID_SDK_VERSION'

Perform a Gradle Sync to download the AWS Mobile SDK components into your app.

Add the following to AndroidManifest.xml:

<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
<service android:name="com.amazonaws.mobileconnectors.s3.transferutility.TransferService" android:enabled="true" />

For Android Q (API 29): API 29 enforces scoped storage access for Android apps. To gain access to legacy external storage, enable the following application property inside AndroidManifest.xml:
```
<manifest ...>
  <application android:requestLegacyExternalStorage="true" ...>
    ...
  </application>
</manifest>
```

Note on Transfer Utility and Amazon Cognito

Transfer Utility generates Amazon S3 pre-signed URLs and uses them to enable background transferring. Using Amazon Cognito Identity, you receive AWS temporary credentials that are valid for up to 60 minutes. It is not possible to generate S3 pre-signed URLs that last longer than 60 minutes. Due to this limitation, the Transfer Utility enforces 50-minute transfer timeouts (10-minute buffer for reducing AWS temporary credential regenerations). After 50 minutes, you receive a transfer failure.

If you expect your app to perform transfers that take longer than 50 minutes, use AmazonS3Client instead of TransferUtility.

Additional Resources

Sample app

For a sample app that demonstrates the TransferUtility capabilities, see S3 TransferUtility Sample.