Skip to content

Commit c15cf28

Browse files
harsh62harsh62
authored
chore: add migration guide from AWS SDK for iOS to Amplify Swift (#4023)
* chore: add migration guide from AWS SDK for iOS to Amplify Swift * updated the FAQ * worked on review comments * re worked on some comments * worked on comments
1 parent beadc84 commit c15cf28

File tree

1 file changed

+173
-0
lines changed

1 file changed

+173
-0
lines changed

‎MobileSDK_To_AmplifySwift_Guidance.md‎

Lines changed: 173 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,173 @@
1+
# Migrating from AWS SDK for iOS to Amplify Swift
2+
3+
This guide helps you migrate your iOS app from the legacy AWS SDK for iOS to the modern [Amplify Swift](https://docs.amplify.aws/gen1/swift/) library.
4+
5+
---
6+
7+
## General Migration Notes
8+
9+
- **Amplify Swift** is the recommended library for all new iOS/macOS/watchOS/tvOS development.
10+
- For any AWS service not yet supported by Amplify, you can use the [AWS SDK for Swift](https://github.com/awslabs/aws-sdk-swift) or reference [Swift SDK code examples](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/swift).
11+
- For IoT, migrate to the [AWS IoT Device SDK for Swift](https://github.com/aws/aws-iot-device-sdk-swift).
12+
- Amplify will make a best-effort attempt to preserve user auth sessions during migration, but some users may need to re-authenticate.
13+
14+
## Choose Your Migration Path
15+
16+
### If you have an **existing Amplify Gen1 project**:
17+
Continue using **Amplify Gen1** and follow the migration tables below. Your existing backend configuration and resources will work seamlessly with Amplify Swift.
18+
19+
### If you **don't have an Amplify project** or are starting fresh:
20+
We recommend using **[Amplify Gen2](https://docs.amplify.aws/react/start/quickstart/)** for new projects. Gen2 provides a modern fullstack TypeScript developer experience with improved performance and simplified deployment.
21+
22+
> **Note**: This guide focuses on migrating to Amplify Gen1 to maintain compatibility with existing Amplify backends. For Gen2 migration guidance, see the [Gen2 documentation](https://docs.amplify.aws/react/start/quickstart/).
23+
24+
---
25+
26+
## Category‑by‑category migration
27+
28+
### Authentication
29+
30+
| AWS Mobile SDK for iOS | Amplify Swift |
31+
| --------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
32+
| [SignUp](https://docs.amplify.aws/gen1/swift/sdk/auth/working-with-api/#signup) | [SignUp](https://docs.amplify.aws/gen1/swift/build-a-backend/auth/enable-sign-in/#register-a-user) |
33+
| [Confirm SignUp](https://docs.amplify.aws/gen1/swift/sdk/auth/working-with-api/#confirm-signup) | [Confirm SignUp](https://docs.amplify.aws/gen1/swift/build-a-backend/auth/enable-sign-in/#register-a-user) |
34+
| [Sign In](https://docs.amplify.aws/gen1/swift/sdk/auth/working-with-api/#signin) | [Sign In](https://docs.amplify.aws/gen1/swift/build-a-backend/auth/enable-sign-in/#sign-in-a-user) |
35+
| [Guest Access](https://docs.amplify.aws/gen1/swift/sdk/auth/guest-access/) | [Guest Access](https://docs.amplify.aws/gen1/swift/build-a-backend/auth/enable-guest-access/) |
36+
| [Federated Identities](https://docs.amplify.aws/gen1/swift/sdk/auth/federated-identities/) | [Federated Identities](https://docs.amplify.aws/gen1/swift/build-a-backend/auth/advanced-workflows/#identity-pool-federation) |
37+
| [Custom Auth Flow](https://docs.amplify.aws/gen1/swift/sdk/auth/custom-auth-flow/) | [Custom Auth Flow](https://docs.amplify.aws/gen1/swift/build-a-backend/auth/sign-in-custom-flow/#configure-auth-category) |
38+
| [Track/Remember Device](https://docs.amplify.aws/gen1/swift/sdk/auth/device-features/) | [Track/Remember Device](https://docs.amplify.aws/gen1/swift/build-a-backend/auth/remember-device/#configure-auth-category) |
39+
| **Drop‑in UI** (Deprecated `AWSMobileClient`) | [**Amplify UI Authenticator**](https://ui.docs.amplify.aws/swift/connected-components/authenticator) |
40+
| [Change Password](https://docs.amplify.aws/gen1/swift/sdk/auth/working-with-api/#force-a-password-reset) | [Change Password](https://docs.amplify.aws/gen1/swift/build-a-backend/auth/manage-passwords/#change-password) |
41+
| [Forgot Password](https://docs.amplify.aws/gen1/swift/sdk/auth/working-with-api/#forgot-password) | [Reset Password](https://docs.amplify.aws/gen1/swift/build-a-backend/auth/multi-step-sign-in/#reset-password) |
42+
| [Tokens & Credentials](https://docs.amplify.aws/gen1/swift/sdk/auth/working-with-api/#managing-security-tokens) | [Accessing Credentials](https://docs.amplify.aws/gen1/swift/build-a-backend/auth/accessing-credentials/) |
43+
| [Global SignOut](https://docs.amplify.aws/gen1/swift/sdk/auth/working-with-api/#global-signout) | [Global SignOut](https://docs.amplify.aws/gen1/swift/build-a-backend/auth/sign-out/#global-sign-out) |
44+
| [Hosted UI](https://docs.amplify.aws/gen1/swift/sdk/auth/hosted-ui/#using-auth0-hosted-ui) | [Sign in with Web UI](https://docs.amplify.aws/gen1/swift/build-a-backend/auth/sign-in-with-web-ui/) |
45+
46+
> **Note** – Social sign‑in in Authenticator for SwiftUI is under active development; track progress in the [GitHub repo](https://github.com/aws-amplify/amplify-ui-swift-authenticator).
47+
48+
---
49+
50+
### Storage
51+
52+
| AWS Mobile SDK for iOS | Amplify Swift |
53+
| -------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
54+
| [Upload File](https://docs.amplify.aws/gen1/swift/sdk/storage/transfer-utility/#upload-a-file) | [Upload File](https://docs.amplify.aws/gen1/swift/build-a-backend/storage/upload/) |
55+
| [Download File](https://docs.amplify.aws/gen1/swift/sdk/storage/transfer-utility/#download-a-file) | [Download File](https://docs.amplify.aws/gen1/swift/build-a-backend/storage/download/#download-to-file) |
56+
| [Progress Tracking](https://docs.amplify.aws/gen1/swift/sdk/storage/transfer-utility/#track-transfer-progress) | Supported via completion handlers & async sequences |
57+
| [Pause Transfers](https://docs.amplify.aws/gen1/swift/sdk/storage/transfer-utility/#pause-a-transfer), [Resume Transfers](https://docs.amplify.aws/gen1/swift/sdk/storage/transfer-utility/#resume-a-transfer) | [Pause/Resume](https://docs.amplify.aws/gen1/swift/build-a-backend/storage/download/#cancel-pause-resume) supported for downloads/uploads |
58+
| [Cancel Transfers](https://docs.amplify.aws/gen1/swift/sdk/storage/transfer-utility/#cancel-a-transfer) | [Cancel](https://docs.amplify.aws/gen1/swift/build-a-backend/storage/download/#cancel-pause-resume) supported for downloads/uploads |
59+
| [Transfer with Metadata](https://docs.amplify.aws/gen1/swift/sdk/storage/transfer-utility/#transfer-with-object-metadata) | Supported (`StorageUploadFileRequest.Options.metadata`) |
60+
| Background Transfers | Not currently supported in Amplify Swift ([see SDK doc](https://docs.amplify.aws/gen1/swift/sdk/storage/transfer-utility/#background-transfers)) |
61+
62+
---
63+
64+
### REST API
65+
66+
(Replace **AWSAPIGatewayClient**)
67+
68+
| AWS Mobile SDK for iOS | Amplify Swift |
69+
| ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
70+
| [Invoke](https://docs.amplify.aws/gen1/swift/sdk/api/rest/) | [Create](https://docs.amplify.aws/gen1/swift/build-a-backend/restapi/set-up-rest-api/#make-a-post-request) / [Fetch](https://docs.amplify.aws/gen1/swift/build-a-backend/restapi/fetch-data/) / [Update](https://docs.amplify.aws/gen1/swift/build-a-backend/restapi/update-data/) / [Delete](https://docs.amplify.aws/gen1/swift/build-a-backend/restapi/delete-data/) |
71+
| [IAM Auth](https://docs.amplify.aws/gen1/swift/sdk/api/rest/#iam-authorization) | [Configure IAM](https://docs.amplify.aws/gen1/swift/build-a-backend/restapi/customize-authz/#iam-authorization) |
72+
| [Cognito User Pools Authorization](https://docs.amplify.aws/gen1/swift/sdk/api/rest/#cognito-user-pools-authorization) | [Cognito User Pools Authorization](https://docs.amplify.aws/gen1/swift/build-a-backend/restapi/customize-authz/#cognito-user-pool-authorization) |
73+
74+
---
75+
76+
### GraphQL API
77+
78+
(Replace **AWSAppSyncClient**)
79+
80+
| AWS Mobile SDK for iOS | Amplify Swift |
81+
| ---------------------- | ----------------------------------------------------------------------------------------------------------------------- |
82+
| [Run Queries](https://docs.amplify.aws/gen1/swift/sdk/api/graphql/#run-a-query), [Run Mutations](https://docs.amplify.aws/gen1/swift/sdk/api/graphql/#run-a-mutation) | [Query Data](https://docs.amplify.aws/gen1/swift/build-a-backend/graphqlapi/query-data/) / [Mutate Data](https://docs.amplify.aws/gen1/swift/build-a-backend/graphqlapi/mutate-data/) |
83+
| [Subscriptions](https://docs.amplify.aws/gen1/swift/sdk/api/graphql/#subscribe-to-data) | [Real‑time Subscribe](https://docs.amplify.aws/gen1/swift/build-a-backend/graphqlapi/subscribe-data/) |
84+
| [Auth Modes](https://docs.amplify.aws/gen1/swift/sdk/api/graphql/#authorization-modes) | [Configure Auth Modes](https://docs.amplify.aws/gen1/swift/build-a-backend/graphqlapi/customize-authz-modes/) |
85+
86+
---
87+
88+
### Push Notifications
89+
90+
> **Pinpoint deprecation notice** – Pinpoint will be retired Oct 30 2026. Plan migrations accordingly.
91+
92+
| AWS SDK for iOS | Amplify Swift |
93+
|-------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------|
94+
| [Setup](https://docs.amplify.aws/gen1/swift/sdk/push-notifications/setup-push-service/) | [Setup](https://docs.amplify.aws/gen1/swift/build-a-backend/push-notifications/set-up-push-notifications/) |
95+
| [Push Notification Service Setup](https://docs.amplify.aws/gen1/swift/sdk/push-notifications/setup-push-service/) | [Push Notification Service Setup](https://docs.amplify.aws/gen1/swift/build-a-backend/push-notifications/set-up-push-service/) |
96+
| [Register Device](https://docs.amplify.aws/gen1/swift/sdk/push-notifications/messaging-campaign/) | [Register Device](https://docs.amplify.aws/gen1/swift/build-a-backend/push-notifications/register-device/) |
97+
| [Record Notification Events](https://docs.amplify.aws/gen1/swift/sdk/push-notifications/messaging-campaign/) | [Record Notification Events](https://docs.amplify.aws/gen1/swift/build-a-backend/push-notifications/record-notifications/) |
98+
99+
---
100+
101+
### Analytics
102+
103+
> **Pinpoint deprecation notice** – Pinpoint will be retired Oct 30 2026. Plan migrations accordingly.
104+
105+
| AWS SDK for iOS | Amplify Swift |
106+
|-------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------|
107+
| [Manually Track Session](https://docs.amplify.aws/gen1/swift/sdk/analytics/getting-started/#add-analytics) | [Automatically Track Session](https://docs.amplify.aws/gen1/swift/build-a-backend/more-features/analytics/set-up-analytics/#initialize-amplify-analytics) |
108+
| [Add Analytics](https://docs.amplify.aws/gen1/swift/sdk/analytics/getting-started/#add-analytics) | [Add Analytics](https://docs.amplify.aws/gen1/swift/build-a-backend/more-features/analytics/set-up-analytics/#initialize-amplify-analytics) |
109+
| [Authentication Events](https://docs.amplify.aws/gen1/swift/sdk/analytics/events/#authentication-events) | [Authentication Events](https://docs.amplify.aws/gen1/swift/build-a-backend/more-features/analytics/record-events/#authentication-events) |
110+
| [Custom Events](https://docs.amplify.aws/gen1/swift/sdk/analytics/events/#custom-events) | [Custom Events](https://docs.amplify.aws/gen1/swift/build-a-backend/more-features/analytics/record-events/) |
111+
112+
---
113+
114+
### AWS IoT
115+
116+
Amplify currently does **not** expose an IoT category. Use the standalone [**AWS IoT Device SDK for Swift**](https://github.com/aws/aws-iot-device-sdk-swift/blob/main/Package.swift), which works side‑by‑side with Amplify.
117+
118+
```swift
119+
// Example: Connect & subscribe with AWS IoT Device SDK Swift
120+
import AwsIot
121+
...
122+
```
123+
124+
---
125+
126+
## When Amplify doesn't cover a service
127+
128+
For AWS services without an Amplify category (e.g., Amazon SQS, EventBridge, DynamoDB Streams) import the **AWS SDK for Swift** directly.\
129+
See runnable examples in the [aws‑doc‑sdk‑examples/swift](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/swift) repository.
130+
131+
> **Tip** – You can share credentials between Amplify and AWS SDK by passing `Amplify.Auth.fetchAuthSession()` credentials into service client configuration.
132+
133+
---
134+
135+
## Migration checklist
136+
137+
1. **Remove** SDK pods / SPM packages for `AWSMobileClient`, `AWSS3TransferUtility`, etc.
138+
2. **Backend setup**:
139+
- **Existing Amplify Gen1 project**: Run `amplify pull` to download your configuration
140+
- **New project**: Set up [Amplify Gen2](https://docs.amplify.aws/react/start/quickstart/) or use existing AWS resources
141+
3. **Add** Amplify Swift libraries and required plugins via SPM.
142+
4. Initialize Amplify in your App's entry point.
143+
5. Replace legacy calls using the tables above.
144+
6. Build & test: verify
145+
- Existing users stay signed in
146+
- S3 uploads/downloads work
147+
- API calls succeed
148+
- Analytics events appear in Pinpoint
149+
150+
---
151+
152+
## FAQ
153+
154+
> **Can I mix AWS Mobile SDK for iOS and Amplify Swift (Amplify v2) in the same app?**
155+
>
156+
> **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.
157+
>
158+
> For a successful migration, you must **fully remove** the AWS Mobile SDK for iOS from your project before integrating Amplify Swift (Amplify v2).
159+
160+
**Will my users be forced to sign in again?**\
161+
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.
162+
163+
---
164+
165+
## Additional resources
166+
167+
- [Amplify Swift Upgrade Guide](https://docs.amplify.aws/gen1/swift/start/project-setup/upgrade-guide/)
168+
- [Amplify UI Authenticator for Swift](https://github.com/aws-amplify/amplify-ui-swift-authenticator)
169+
- [AWS IoT Device SDK for Swift announcement](https://aws.amazon.com/blogs/developer/introducing-the-aws-iot-device-sdk-for-swift-developer-preview/)
170+
171+
---
172+
173+
© Amazon Web Services 2025 – Documentation links verified **July 16 2025**.

0 commit comments

Comments
 (0)