Set up Amplify Geo

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.

Amplify Geo provides APIs and map UI components for mobile app development such that you can add maps to your app in just a few lines of code. Amplify Geo APIs are powered by Amazon Location Service and the map UI components from MapLibre are already integrated with the Geo APIs. You can quickly get started using Amplify CLI to provision your map resources.

Follow this guide to get started with Amplify Geo through the Amplify CLI.

Note:

If you want to use existing Amazon Location Service resources follow this guide instead.
If you want to use Amazon Location Service APIs not directly supported by Geo, use the escape hatch to access the Amazon Location Service SDK.

Prerequisites

An iOS application targeting at least iOS 13.0, using Xcode 12.0 or higher, with Amplify libraries integrated
- For a full example of creating iOS project, please follow the project setup walkthrough

Provisioning resources through CLI

Prerequisite: Install and configure the Amplify CLI

To start provisioning Geo resources in the backend, go to your project directory and execute the command:

1amplify add geo

The CLI will prompt configuration options for the Geo category for what type of capability you want to add and default or advanced settings. The add command automatically creates the backend configuration. Once all your configuration is complete run the following:

1amplify push

Upon completion, amplifyconfiguration.json should be updated to reference provisioned backend geo resources. Note that this file should already be a part of your project if you followed the Project setup walkthrough.

Install Amplify Libraries

The Geo plugin is dependent on Cognito Auth.

To install Amplify Geo and Authentication to your application, open your project in Xcode and select File > Add Packages....
Enter the Amplify iOS GitHub repo URL (https://github.com/aws-amplify/amplify-swift) into the search bar and and hit Enter Wait for the result to load. You'll see the repository rules for which version of amplify-ios-mapLibre 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, then click Add Package.
Lastly, choose AWSLocationGeoPlugin, AWSCognitoAuthPlugin, and Amplify. Then click Finish.

Troubleshooting: If you intend on using the Amplify-MapLibre adapter to render maps, you must use Swift Package Manager to add Amplify. The adapter is incompatible with existing Amplify dependencies added via CocoaPods.

To install the Amplify Geo and Authentication to your application, add both "AmplifyPlugins/AWSLocationGeoPlugin" and "AmplifyPlugins/AWSCognitoAuthPlugin" to your Podfile (Because IAM credential is required to access Amazon Location Service, "AWSCognitoAuthPlugin" also needs to be installed). Your Podfile should look similar to:

1target 'MyAmplifyApp' do
2  use_frameworks!
3  pod 'Amplify'
4  pod 'AmplifyPlugins/AWSLocationGeoPlugin'
5  pod 'AmplifyPlugins/AWSCognitoAuthPlugin'
6end

To install, download and resolve these pods, execute the command:

1pod install --repo-update

Now you can open your project by opening the .xcworkspace file using the following command:

1xed .

Initialize Amplify Geo

To initialize the Amplify Geo, use the Amplify.addPlugin() method to add the AWSLocationGeoPlugin. Next, finish configuring Amplify by calling Amplify.configure().

Open the main file of the application - AppDelegate.swift or <YOUR_APP_NAME>App.swift depending on the app's life cycle - and add the following import statements at the top of the file:

1import Amplify
2import AWSLocationGeoPlugin

1import Amplify
2import AmplifyPlugins

In the same file, create a function to configure Amplify:

1func configureAmplify() {
2    do {
3        try Amplify.add(plugin: AWSCognitoAuthPlugin())
4        try Amplify.add(plugin: AWSLocationGeoPlugin())
5        try Amplify.configure()
6        print("Initialized Amplify");
7    } catch {
8        print("Could not initialize Amplify: \(error)")
9    }
10}

Now call the configureAmplify() function in the starting point of your application.

1@main
2struct <YOUR_APP_NAME>App: App {
3    // add a default initializer and configure Amplify
4    public init() {
5        configureAmplify()
6    }
7}

1@UIApplicationMain
2class AppDelegate: UIResponder, UIApplicationDelegate {
3    func application(_: UIApplication,
4                     didFinishLaunchingWithOptions _: [UIApplication.LaunchOptionsKey: Any]?
5    ) -> Bool {
6        configureAmplify()
7        return true
8    }
9    // ...
10}

Upon building and running this application you should see the following in your console window:

1Initialized Amplify

Configure maps