Skip to content

Commit 08aa373

Browse files
harsh62harsh62
committed
chore: add migration guide from AWS SDK for iOS to Amplify Swift
1 parent beadc84 commit 08aa373

File tree

1 file changed

+168
-0
lines changed

1 file changed

+168
-0
lines changed

‎MobileSDK_To_AmplifySwift_Guidance.md

Lines changed: 168 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,168 @@
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/blob/main/Package.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+
---
15+
16+
## Category‑by‑category migration
17+
18+
### Authentication
19+
20+
| AWS Mobile SDK for iOS | Amplify Swift |
21+
| --------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
22+
| [SignUp](https://docs.amplify.aws/gen1/swift/sdk/auth/working-with-api/#signup) | [Sign Up](https://docs.amplify.aws/gen1/swift/sdk/auth/working-with-api/#signup) |
23+
| [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) |
24+
| [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) |
25+
| [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/) |
26+
| [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) |
27+
| [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) |
28+
| [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) |
29+
| **Drop‑in UI** (Deprecated `AWSMobileClient`) | [**Amplify UI Authenticator**](https://ui.docs.amplify.aws/swift/connected-components/authenticator) |
30+
| [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) |
31+
| [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) |
32+
| [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/) |
33+
| [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) |
34+
| [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/prev/build-a-backend/auth/sign-in-with-web-ui/) |
35+
36+
> **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).
37+
38+
---
39+
40+
### Storage
41+
42+
| AWS Mobile SDK for iOS | Amplify Swift |
43+
| -------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
44+
| [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/) |
45+
| [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) |
46+
| Progress Tracking | Supported via completion handlers & async sequences |
47+
| Pause/Resume Transfers | [Pause/Resume](https://docs.amplify.aws/gen1/swift/build-a-backend/storage/download/#cancel-pause-resume) supported for downloads/uploads |
48+
| Cancel Transfers | [Cancel](https://docs.amplify.aws/gen1/swift/build-a-backend/storage/download/#cancel-pause-resume) supported for downloads/uploads |
49+
| Transfer with Metadata | Supported (`StorageUploadFileRequest.Options.metadata`) |
50+
| Background Transfers | Not currently supported in Amplify Swift ([see SDK doc](https://docs.amplify.aws/gen1/swift/sdk/storage/transfer-utility/#background-transfers)) |
51+
52+
---
53+
54+
### REST API
55+
56+
(Replace **AWSAPIGatewayClient**)
57+
58+
| AWS Mobile SDK for iOS | Amplify Swift |
59+
| ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
60+
| [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/) |
61+
| [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) |
62+
| [Cognito User Pools](https://docs.amplify.aws/gen1/swift/sdk/api/rest/#cognito-user-pool-authorization) | [CUP Auth](https://docs.amplify.aws/gen1/swift/build-a-backend/restapi/customize-authz/#cognito-user-pool-authorization) |
63+
64+
---
65+
66+
### GraphQL API
67+
68+
(Replace **AWSAppSyncClient**)
69+
70+
| AWS Mobile SDK for iOS | Amplify Swift |
71+
| ---------------------- | ----------------------------------------------------------------------------------------------------------------------- |
72+
| Queries / Mutations | [Create / Read / Update / Delete](https://docs.amplify.aws/gen1/swift/build-a-backend/graphqlapi/create-update-delete/) |
73+
| Subscriptions | [Real‑time Subscribe](https://docs.amplify.aws/gen1/swift/build-a-backend/graphqlapi/subscribe-to-data/) |
74+
| Auth Modes | [Configure Auth Modes](https://docs.amplify.aws/gen1/swift/build-a-backend/graphqlapi/configure-auth-modes/) |
75+
76+
---
77+
78+
### Push Notifications
79+
80+
> **Pinpoint deprecation notice** – Pinpoint will be retired Oct 30 2026. AWS End User Messaging is the recommended successor. Plan migrations accordingly.
81+
82+
| AWS SDK for iOS | Amplify Swift |
83+
|-------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------|
84+
| [Setup](https://docs.amplify.aws/gen1/swift/sdk/push-notifications/getting-started/) | [Setup](https://docs.amplify.aws/gen1/swift/build-a-backend/push-notifications/set-up-push-notifications/) |
85+
| [Push Notification Service Setup](https://docs.amplify.aws/gen1/swift/sdk/push-notifications/messaging-campaign/) | [Push Notification Service Setup](https://docs.amplify.aws/gen1/swift/build-a-backend/push-notifications/set-up-push-service/) |
86+
| [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/) |
87+
| [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/) |
88+
89+
---
90+
91+
### Analytics
92+
93+
> **Pinpoint deprecation notice** – Pinpoint will be retired Oct 30 2026. AWS End User Messaging is the recommended successor. Plan migrations accordingly.
94+
95+
| AWS SDK for iOS | Amplify Swift |
96+
|-------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------|
97+
| [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) |
98+
| [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) |
99+
| [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) |
100+
| [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/) |
101+
| [Monetization Events](https://docs.amplify.aws/gen1/swift/sdk/analytics/events/#monetization-events) | Please check notes (not directly supported in Amplify Swift as of July 2025) |
102+
103+
---
104+
105+
### AWS IoT
106+
107+
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.
108+
109+
```swift
110+
// Example: Connect & subscribe with AWS IoT Device SDK Swift
111+
import AwsIot
112+
...
113+
```
114+
115+
---
116+
117+
## When Amplify doesn’t cover a service
118+
119+
For AWS services without an Amplify category (e.g., Amazon SQS, EventBridge, DynamoDB Streams) import the **AWS SDK for Swift** directly.\
120+
See runnable examples in the [aws‑doc‑sdk‑examples/swift](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/swift) repository.
121+
122+
> **Tip** – You can share credentials between Amplify and AWS SDK by passing `Amplify.Auth.fetchAuthSession()` credentials into service client configuration.
123+
124+
---
125+
126+
## Migration checklist
127+
128+
1. **Remove** SDK pods / SPM packages for `AWSMobileClient`, `AWSS3TransferUtility`, etc.
129+
2. **Create or import** your backend in **Amplify Gen 2** console and download the generated configuration (or run `amplify pull`).
130+
3. **Add** Amplify libraries and required plugins via SPM.
131+
4. Initialize Amplify in your App’s entry point.
132+
5. Replace legacy calls using the tables above.
133+
6. Build & test: verify
134+
- Existing users stay signed in
135+
- S3 uploads/downloads work
136+
- API calls succeed
137+
- Analytics events appear in Pinpoint
138+
139+
---
140+
141+
## FAQ
142+
143+
> **Can I mix AWS Mobile SDK for iOS and Amplify Swift (Amplify v2) in the same app?**
144+
>
145+
> **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.
146+
>
147+
> For a successful migration, you must **fully remove** the AWS Mobile SDK for iOS from your project before integrating Amplify Swift (Amplify v2).
148+
149+
**Will my users be forced to sign in again?**\
150+
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.
151+
152+
**Does Amplify Storage support background transfers?**\
153+
Yes. The S3 plugin internally uses `TransferUtility` and automatically resumes incomplete uploads/downloads.
154+
155+
**Can I mix Amplify Gen 1 and Gen 2 code?**\
156+
Yes, but prefer a single generation in production apps to avoid redundant dependencies. Gen 2 currently focuses on web & React; mobile Gen 2 is in preview.
157+
158+
---
159+
160+
## Additional resources
161+
162+
- [Amplify Swift Upgrade Guide](https://docs.amplify.aws/gen1/swift/start/project-setup/upgrade-guide/)
163+
- [Amplify UI Authenticator for Swift](https://github.com/aws-amplify/amplify-ui-swift-authenticator)
164+
- [AWS IoT Device SDK for Swift announcement](https://aws.amazon.com/blogs/developer/introducing-the-aws-iot-device-sdk-for-swift-developer-preview/)
165+
166+
---
167+
168+
© Amazon Web Services 2025 – Documentation links verified **July 16 2025**.

0 commit comments

Comments
 (0)