Skip to content

MobileSDK_To_AmplifySwift_Guidance.md

Latest commit

 

History

History
173 lines (121 loc) · 16.8 KB

MobileSDK_To_AmplifySwift_Guidance.md

File metadata and controls

173 lines (121 loc) · 16.8 KB
Raw

Migrating from AWS SDK for iOS to Amplify Swift

This guide helps you migrate your iOS app from the legacy AWS SDK for iOS to the modern Amplify Swift library.

General Migration Notes

  • Amplify Swift is the recommended library for all new iOS/macOS/watchOS/tvOS development.
  • For any AWS service not yet supported by Amplify, you can use the AWS SDK for Swift or reference Swift SDK code examples.
  • For IoT, migrate to the AWS IoT Device SDK for Swift.
  • Amplify will make a best-effort attempt to preserve user auth sessions during migration, but some users may need to re-authenticate.

Choose Your Migration Path

If you have an existing Amplify Gen1 project:

Continue using Amplify Gen1 and follow the migration tables below. Your existing backend configuration and resources will work seamlessly with Amplify Swift.

If you don't have an Amplify project or are starting fresh:

We recommend using Amplify Gen2 for new projects. Gen2 provides a modern fullstack TypeScript developer experience with improved performance and simplified deployment.

Note: This guide focuses on migrating to Amplify Gen1 to maintain compatibility with existing Amplify backends. For Gen2 migration guidance, see the Gen2 documentation.

Category‑by‑category migration

Authentication

AWS Mobile SDK for iOS Amplify Swift
SignUp SignUp
Confirm SignUp Confirm SignUp
Sign In Sign In
Guest Access Guest Access
Federated Identities Federated Identities
Custom Auth Flow Custom Auth Flow
Track/Remember Device Track/Remember Device
Drop‑in UI (Deprecated AWSMobileClient) Amplify UI Authenticator
Change Password Change Password
Forgot Password Reset Password
Tokens & Credentials Accessing Credentials
Global SignOut Global SignOut
Hosted UI Sign in with Web UI

Note – Social sign‑in in Authenticator for SwiftUI is under active development; track progress in the GitHub repo.

Storage

AWS Mobile SDK for iOS Amplify Swift
Upload File Upload File
Download File Download File
Progress Tracking Supported via completion handlers & async sequences
Pause Transfers, Resume Transfers Pause/Resume supported for downloads/uploads
Cancel Transfers Cancel supported for downloads/uploads
Transfer with Metadata Supported (StorageUploadFileRequest.Options.metadata)
Background Transfers Not currently supported in Amplify Swift (see SDK doc)

REST API

(Replace AWSAPIGatewayClient)

AWS Mobile SDK for iOS Amplify Swift
Invoke Create / Fetch / Update / Delete
IAM Auth Configure IAM
Cognito User Pools Authorization Cognito User Pools Authorization

GraphQL API

(Replace AWSAppSyncClient)

AWS Mobile SDK for iOS Amplify Swift
Run Queries, Run Mutations Query Data / Mutate Data
Subscriptions Real‑time Subscribe
Auth Modes Configure Auth Modes

Push Notifications

Pinpoint deprecation notice – Pinpoint will be retired Oct 30 2026. Plan migrations accordingly.

AWS SDK for iOS Amplify Swift
Setup Setup
Push Notification Service Setup Push Notification Service Setup
Register Device Register Device
Record Notification Events Record Notification Events

Analytics

Pinpoint deprecation notice – Pinpoint will be retired Oct 30 2026. Plan migrations accordingly.

AWS SDK for iOS Amplify Swift
Manually Track Session Automatically Track Session
Add Analytics Add Analytics
Authentication Events Authentication Events
Custom Events Custom Events

AWS IoT

Amplify currently does not expose an IoT category. Use the standalone AWS IoT Device SDK for Swift, which works side‑by‑side with Amplify.

// Example: Connect & subscribe with AWS IoT Device SDK Swift
import AwsIot
...

When Amplify doesn't cover a service

For AWS services without an Amplify category (e.g., Amazon SQS, EventBridge, DynamoDB Streams) import the AWS SDK for Swift directly.
See runnable examples in the aws‑doc‑sdk‑examples/swift repository.

Tip – You can share credentials between Amplify and AWS SDK by passing Amplify.Auth.fetchAuthSession() credentials into service client configuration.

Migration checklist

  1. Remove SDK pods / SPM packages for AWSMobileClient, AWSS3TransferUtility, etc.
  2. Backend setup:
    • Existing Amplify Gen1 project: Run amplify pull to download your configuration
    • New project: Set up Amplify Gen2 or use existing AWS resources
  3. Add Amplify Swift libraries and required plugins via SPM.
  4. Initialize Amplify in your App's entry point.
  5. Replace legacy calls using the tables above.
  6. Build & test: verify
    • Existing users stay signed in
    • S3 uploads/downloads work
    • API calls succeed
    • Analytics events appear in Pinpoint

FAQ

Can I mix AWS Mobile SDK for iOS and Amplify Swift (Amplify v2) in the same app?

No. AWS Amplify explicitly does not support using the AWS Mobile SDK for iOS and Amplify Swift (Amplify v2) together in the same app. This is due to overlapping implementations, conflicting dependencies, and import issues. Attempting to use both in the same project can result in unpredictable behavior, build errors, and runtime issues.

For a successful migration, you must fully remove the AWS Mobile SDK for iOS from your project before integrating Amplify Swift (Amplify v2).

Will my users be forced to sign in again?
No. When Amplify is pointed at the same Cognito User Pool and key‑chain location, it detects cached refresh tokens and continues the session automatically.

Additional resources

© Amazon Web Services 2025 – Documentation links verified July 16 2025.