Amplify project setup

Amplify iOS v1 is now in Maintenance Mode until May 31st, 2024. This means that we will continue to include updates to ensure compatibility with backend services and security. No new features will be introduced in v1.

Please use the latest version (v2) of Amplify Library for Swift to get started.

If you are currently using v1, follow these instructions to upgrade to v2.

Amplify libraries should be used for all new cloud connected applications. If you are currently using the AWS Mobile SDK for iOS, you can access the documentation here.

For this section you will set up a skeleton project so that Amplify categories can be added to it.

1. Create a new project

Open Xcode. From the menu bar, select "File -> New -> Project..."

Select iOS tab, choose Application type as App and then click on Next.

GSA

Fill in the following for your project:

  • Product Name: MyAmplifyApp
  • Interface: SwiftUI
  • Language: Swift
  • Tap Next

GSA

After tapping Next, select where you would like to save your project, then tap Create. In this example, you will choose: ~/Developer GSA

You should now have an empty iOS project without Amplify.

2. Install Amplify Libraries

To start adding the Amplify Libraries to your iOS project, open your project in Xcode and select File > Add Packages...

Add package dependency

Enter the Amplify iOS GitHub repo URL (https://github.com/aws-amplify/amplify-swift) into the search bar and hit Enter. Wait for the result to load.

You'll see the Amplify iOS repository rules for which version of Amplify you want Swift Package Manager to install. Choose the dependency rule Up to Next Major Version, as it will use the latest compatible version of the dependency that can be detected from the main branch, then click Add Package.

Search for repo

Lastly, choose which of the libraries you want added to your project. Always select the Amplify library. The "Plugin" to install depends on which categories you are using:

  • API: AWSAPIPlugin

  • Analytics: AWSPinpointAnalyticsPlugin

  • Auth: AWSCognitoAuthPlugin

  • DataStore: AWSDataStorePlugin

  • Geo: AWSLocationGeoPlugin

  • Storage: AWSS3StoragePlugin

    Note: AWSPredictionsPlugin is not currently supported through Swift Package Manager due to different minimum iOS version requirements. Support for this will eventually be added.

Select dependencies

Select all that are appropriate, then click Add Package.

You can always go back and modify which SPM packages are included in your project by opening the Package Dependencies tab for your project: Click on the Project file in the Xcode navigator, then click on your project's icon, then select the Package Dependencies tab.

You must explicitly import plugins in your app code when using Swift Package Manager to install Amplify, as in:

import Amplify import AWSAPIPlugin import AWSDataStorePlugin
1import Amplify
2import AWSAPIPlugin
3import AWSDataStorePlugin

This is a result of Swift Package Manager's importing only relevant pieces of the dependency being installed–in this case, the categories of Amplify.

Before starting this step, please make sure you close Xcode.

Open a terminal and change directories to your project. For example, if you created your project in the folder ~/Developer, you can:

cd ~/Developer/MyAmplifyApp
1cd ~/Developer/MyAmplifyApp

In order to initialize your project with the CocoaPods package manager, execute the command:

pod init
1pod init

After doing this, you should see a newly created file called Podfile. This file is used to describe what packages your project depends on.

Update the file to include the Amplify pod:

target 'MyAmplifyApp' do use_frameworks! pod 'Amplify' end
1target 'MyAmplifyApp' do
2 use_frameworks!
3 pod 'Amplify'
4end

To download and install the Amplify pod into your project, execute the command:

pod install --repo-update
1pod install --repo-update

After doing this, you should now see file called MyAmplifyApp.xcworkspace. You are required to use this file from now on instead of the .xcodeproj file. To open your workspace, execute the command:

xed .
1xed .

This should open the newly generated MyAmplifyApp.xcworkspace in Xcode.

3. Provision the backend with Amplify CLI

To start provisioning resources in the backend, change directories to your project directory and run amplify init:

cd ~/Developer/MyAmplifyApp/ amplify init
1cd ~/Developer/MyAmplifyApp/
2amplify init

Enter the following when prompted:

? Enter a name for the project MyAmplifyApp ? Enter a name for the environment dev ? Choose your default editor: Visual Studio Code ? Choose the type of app that you're building ios ? Do you want to use an AWS profile? Yes ? Please choose the profile you want to use default
1? Enter a name for the project
2 MyAmplifyApp
3? Enter a name for the environment
4 dev
5? Choose your default editor:
6 Visual Studio Code
7? Choose the type of app that you're building
8 ios
9? Do you want to use an AWS profile?
10 Yes
11? Please choose the profile you want to use
12 default

Upon successfully running amplify init, you should see two new created files in your project directory: amplifyconfiguration.json and awsconfiguration.json. These two files must be manually added to your project so that they are bundled with your application. This is required so that Amplify libraries know how to reach your provisioned backend resources.

To add these configuration files to your project, open finder within your project and drag both amplifyconfiguration.json and awsconfiguration.json to the Xcode window, under your project's folder as seen in this screenshot:

GSA

  • Enable Copy items if needed if not already enabled
  • For “Added folders”, have Create groups selected.
  • For “Add to targets”, make sure the app target (MyAmplifyApp) is checked.

Click Finish to add these files to your project as shown in this screenshot:

GSA

Now you can build (Cmd+b) and run (Cmd+r) your application.

4. Initialize Amplify in the application

Open AppDelegate.swift or MyAmplifyApp.swift and add import Amplify at the top of the file:

import Amplify
1import Amplify

Update the following function to verify that Amplify can be compiled into your project:

func application( _ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]? ) -> Bool { do { try Amplify.configure() } catch { print("An error occurred setting up Amplify: \(error)") } return true }
1func application(
2 _ application: UIApplication,
3 didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
4) -> Bool {
5 do {
6 try Amplify.configure()
7 } catch {
8 print("An error occurred setting up Amplify: \(error)")
9 }
10 return true
11}

Note: If your app conforms to the App protocol, you can use your own AppDelegate class. Implement an AppDelegate and point Swift UI's UIApplicationDelegateAdaptor property wrapper to it, as below.

class AppDelegate: NSObject, UIApplicationDelegate { func application( _ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey : Any]? = nil ) -> Bool { do { try Amplify.configure() } catch { print("An error occurred setting up Amplify: \(error)") } return true } } @main struct MyAmplifyApp: App { @UIApplicationDelegateAdaptor(AppDelegate.self) var appDelegate var body: some Scene { WindowGroup { ContentView() } } }
1class AppDelegate: NSObject, UIApplicationDelegate {
2 func application(
3 _ application: UIApplication,
4 didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey : Any]? = nil
5 ) -> Bool {
6 do {
7 try Amplify.configure()
8 } catch {
9 print("An error occurred setting up Amplify: \(error)")
10 }
11 return true
12 }
13}
14@main
15struct MyAmplifyApp: App {
16 @UIApplicationDelegateAdaptor(AppDelegate.self) var appDelegate
17
18 var body: some Scene {
19 WindowGroup {
20 ContentView()
21 }
22 }
23}

Build your project (Cmd+b), then you have successfully added the Amplify library to your project and you should be able to run the application.

Optionally, if you'd like to see additional log messages of what amplify is doing during configuration, you can turn on verbose logging before calling Amplify.configure():

do { Amplify.Logging.logLevel = .verbose // Configure Amplify as usual... try Amplify.configure() // ...
1do {
2 Amplify.Logging.logLevel = .verbose
3 // Configure Amplify as usual...
4 try Amplify.configure()
5 // ...

Re-running the application with verbose logging on, you will see the following messages:

[Amplify] Configuring [Amplify] Configuration: nil
1[Amplify] Configuring
2[Amplify] Configuration: nil

Next steps

Congratulations! You've created a skeleton app and are ready to start adding Amplify categories to your application. The following are some categories that you can start to build into your application:

  • Analytics - for logging metrics and understanding your users
  • API (GraphQL) - for adding a GraphQL endpoint to your app
  • API (REST) - for adding a REST endpoint to your app
  • Authentication - for managing your users
  • DataStore - for making it easier to program for a distributed data store for offline and online scenarios
  • Geo - to use location data and map UI components.
  • Predictions - to detect text, images, and more!
  • Storage - store complex objects like pictures and videos to the cloud.