---
title: Get started with the iOS Swift SDK
description: "Install the Amplitude iOS Swift SDK, initialize it, send a first event, and fix the Xcode, CocoaPods, and upload problems that stop events from arriving."
product: analytics
lang: en
last_updated: 2026-11-05
token_estimate: 3195
---
# Get started with the iOS Swift SDK

- **Package:** `AmplitudeSwift` ([cocoapods](https://cocoapods.org/pods/AmplitudeSwift))
- **Latest version:** 1.19.4

Install the iOS Swift SDK (`AmplitudeSwift`), initialize it, and send one custom event to Amplitude. Each step lists the problems that commonly break that step, so you can fix a problem where it happens. For the full option list, go to [Configuration options](https://amplitude.com/docs/sdks/analytics/ios/ios-swift-sdk/reference#configuration-options). For changes between versions, go to the [iOS Swift SDK release notes](https://amplitude.com/docs/sdks/analytics/ios/ios-swift-sdk-release-notes).

> For AI agents: a documentation index is available at [/docs/llms.txt](/docs/llms.txt). Append `.md` to any page URL for markdown, or send `Accept: text/markdown`.

The iOS Swift SDK is the analytics-only package. If you also need Session Replay or Feature Experiment, install the [Unified SDK for Swift](https://amplitude.com/docs/sdks/analytics/ios/unified-sdk/get-started) (`AmplitudeUnified`) instead. It includes `AmplitudeSwift`, so don't add both packages to the same app. To compare the packages, go to [Choose an iOS installation](https://amplitude.com/docs/sdks/analytics/ios/choose-an-ios-installation).

## Prerequisites

- An Amplitude project and its API key. Find the key in _Settings > Projects > your project > General_.
- The data center your organization uses: US (default) or EU.
- The latest SDK release, or a pinned version you check against the [release notes](https://amplitude.com/docs/sdks/analytics/ios/ios-swift-sdk-release-notes) for the features you use.
- Xcode 16.3 or later (Swift 6.1 or later). The SDK source uses Swift 6.1 syntax, and the SDK's release builds use Xcode 16.3.
- A deployment target of at least iOS 13.0, macOS 10.15, tvOS 13.0, watchOS 7.0, or visionOS 1.0.

## Install the SDK

Choose one installation method. Swift Package Manager is built into Xcode and needs no extra tools.

#### Swift Package Manager

1. In Xcode, select _File > Add Package Dependencies_.
2. Enter `https://github.com/amplitude/Amplitude-Swift` in the search field.
3. Set **Dependency Rule** to **Up to Next Major Version**, starting from `1.19.4`.
4. Select **Add Package**, then add the `AmplitudeSwift` product to your app target.

To add the SDK to a `Package.swift` manifest instead:

```swift
dependencies: [
    .package(url: "https://github.com/amplitude/Amplitude-Swift", from: "1.19.4"),
],
targets: [
    .target(
        name: "MyApp",
        dependencies: [.product(name: "AmplitudeSwift", package: "Amplitude-Swift")]
    ),
]
```

#### CocoaPods

1. Add the pod to your `Podfile`:

   ```ruby
   pod 'AmplitudeSwift', '~> 1.19.4'
   ```

   `~>` with a three-part version accepts patch releases of that minor version only. To accept every 1.x release, use `'~> 1.0'`.
2. Run `pod install`, then open the `.xcworkspace` file that CocoaPods creates.

#### Carthage

1. Add the SDK to your `Cartfile`:

   ```text
   github "amplitude/Amplitude-Swift" ~> 1.19.4
   ```
2. Run `carthage update --use-xcframeworks`.
3. In your app target, link `AmplitudeSwift` and its two dependencies, `AnalyticsConnector` and `AmplitudeCore`, from `Carthage/Build`. Carthage also builds `AmplitudeSwiftNoUIKit`, a variant without UIKit autocapture. Link only one of the two SDK frameworks.

For details, go to the [Carthage documentation](https://github.com/Carthage/Carthage#adding-frameworks-to-an-application).

### Fix installation problems

| Symptom | Cause | Fix |
| --- | --- | --- |
| `No such module 'AmplitudeSwift'` | The target that imports the SDK doesn't link the `AmplitudeSwift` product, or CocoaPods users opened the `.xcodeproj`. | Add `AmplitudeSwift` under the target's **Frameworks, Libraries, and Embedded Content**. With CocoaPods, open the `.xcworkspace`. |
| CocoaPods: `Specs satisfying the `AmplitudeSwift (...)` dependency were found, but they required a higher minimum deployment target.` | The `platform` in your `Podfile` is below the SDK's minimum, such as iOS 12. | Raise `platform :ios` to `'13.0'` or later. |
| CocoaPods: `None of your spec sources contain a spec satisfying the dependency: `AmplitudeSwift (...)`.` | Your local CocoaPods spec repo predates the version you requested. | Run `pod install --repo-update`. |
| Build errors in the SDK's `Configuration.swift` | Xcode is older than 16.3, so its compiler doesn't accept the Swift 6.1 syntax the SDK uses. | Update to Xcode 16.3 or later. |
| Duplicate Amplitude symbols, or events sent twice | The app links both `AmplitudeSwift` and the Unified SDK, or both Carthage SDK frameworks. | Keep one Amplitude analytics package in the app. |

## Initialize the SDK

Create one `Amplitude` instance when your app launches, and keep a strong reference to it. For example, store the instance as a property of your `App` struct or `AppDelegate`, or in a shared singleton. Use that instance for every call.

#### Swift

```swift
import AmplitudeSwift

let amplitude = Amplitude(configuration: Configuration(
    apiKey: "YOUR_API_KEY"
))
```

#### Objective-C

```objc
@import AmplitudeSwift;

AMPConfiguration *configuration = [AMPConfiguration initWithApiKey:@"YOUR_API_KEY"];
Amplitude *amplitude = [Amplitude initWithConfiguration:configuration];
```

If your project uses the EU data center, set `serverZone`:

#### Swift

```swift
let amplitude = Amplitude(configuration: Configuration(
    apiKey: "YOUR_API_KEY",
    serverZone: .EU
))
```

#### Objective-C

```objc
@import AmplitudeSwift;
@import AmplitudeCore; // Declares AMPServerZone.

AMPConfiguration *configuration = [AMPConfiguration initWithApiKey:@"YOUR_API_KEY"];
configuration.serverZone = AMPServerZoneEU;
Amplitude *amplitude = [Amplitude initWithConfiguration:configuration];
```

By default, the SDK tracks sessions (`session_start` and `session_end` events) and nothing else automatically. To add app lifecycle events, screen views, element interactions, network requests, or frustration interactions, go to [Autocapture](https://amplitude.com/docs/sdks/analytics/ios/ios-swift-sdk/instrument-and-configure#autocapture).

Swift requires `Configuration` arguments in their declared order. If Xcode reports an argument order error, check the order in [Configuration options](https://amplitude.com/docs/sdks/analytics/ios/ios-swift-sdk/reference#configuration-options).

### Fix initialization problems

| Symptom | Cause | Fix |
| --- | --- | --- |
| Events never upload, and debug logs never show `Start flushing ... events` | The instance was a local variable, and Swift released it when the function returned. Its upload timer stopped with it. | Store the instance in a property or singleton that lives as long as the app. |
| Warning: `Configured deviceId <id> is a known invalid value shared by many devices` | You passed a placeholder `deviceId`, such as all zeros, to `Configuration`. | Remove the `deviceId` argument so the SDK picks one, or pass a real per-device ID. |
| No `Debug:` lines in the Xcode console after you set `amplitude.configuration.logLevel` | The SDK copies `logLevel` to its logger only at initialization. Changing it later has no effect. | Pass `logLevel` to `Configuration` when you create the instance. Go to [Set the log level](https://amplitude.com/docs/sdks/analytics/ios/ios-swift-sdk/instrument-and-configure#set-the-log-level). |
| Callback reports `400`, `Invalid API key: ...` | The key is wrong, or belongs to a project in the other data center. | Copy the key again, and set `serverZone: .EU` only for EU projects. |

## Send a first event

Track one custom event, then call `flush()` to upload it right away. To see the result, pass a `callback` to `Configuration`. The SDK calls the callback once for each event after the upload finishes.

#### Swift

```swift
let amplitude = Amplitude(configuration: Configuration(
    apiKey: "YOUR_API_KEY",
    callback: { event, code, message in
        print(event.eventType, code, message)
    }
))

amplitude.track(
    eventType: "Sign Up Clicked",
    eventProperties: ["plan": "starter"]
)
amplitude.flush()
// Sign Up Clicked 200 Successfully send event
```

#### Objective-C

```objc
AMPConfiguration *configuration = [AMPConfiguration initWithApiKey:@"YOUR_API_KEY"];
configuration.callback = ^(AMPBaseEvent *event, NSInteger code, NSString *message) {
    NSLog(@"%@ %ld %@", event.eventType, (long)code, message);
};
Amplitude *amplitude = [Amplitude initWithConfiguration:configuration];

[amplitude track:@"Sign Up Clicked" eventProperties:@{@"plan": @"starter"}];
[amplitude flush];
// Sign Up Clicked 200 Successfully send event
```

Without `flush()`, the SDK uploads queued events every 30 seconds (`flushIntervalMillis`), when the queue reaches 30 events (`flushQueueSize`), or when the app moves to the background. Remove the `flush()` call after you confirm the setup.

The callback fires only for responses `200`, `400`, and `413`. For other failures, such as rate limits, server errors, or no network, the SDK keeps the event, retries, and logs an error instead.

### Fix upload problems

| Callback `code` and `message`, or log line | Cause | Fix |
| --- | --- | --- |
| `400`, `Invalid API key: <your key>` | Amplitude doesn't recognize the key in this data center. The SDK drops every event in the request. | Copy the key again and check `serverZone`. |
| `400`, other server error text | Amplitude rejected some events, for example for invalid fields. The SDK drops those events and uploads the rest again. | Read the error log `Response failed with code400: {...}`, which shows the full server response, and fix the events it names. |
| `413`, server error text | The request was too large. The SDK splits the batch and retries. It drops an event that's too large on its own. | Reduce the size of the event's properties. |
| No callback. Error log `Response failed with code429: {...}`, then `Request failed 1 times, send next event file in 1.0 seconds` | Amplitude throttled the device or user. The SDK keeps the events and retries after 1, 2, 4, 8, 16, and 32 seconds. Server errors (`5xx`) and timeouts (`408`) behave the same way. | Reduce how often the app sends events. If every retry fails, the SDK goes offline (next row). |
| No callback. Error log `Conection failed with error: ..., marking offline` | The device has no network, the host is unreachable, or App Transport Security blocked an `http://` `serverUrl`. | Check the network and any `serverUrl` value. The SDK uploads when the connection returns. Go to [Use offline mode](https://amplitude.com/docs/sdks/analytics/ios/ios-swift-sdk/instrument-and-configure#use-offline-mode). |
| No callback. Error log `Request failed more than 6 times, marking offline` | Uploads failed more than `flushMaxRetries` (6) times in a row, so the SDK stopped trying. | Fix the cause in the earlier log lines. The SDK resumes when network connectivity changes, or when you set `amplitude.configuration.offline = false` and call `flush()`. |
| No callback. Log `Skip event based on opt out configuration` | Opt-out is on, so the SDK drops events before it queues them. | Set `amplitude.optOut = false`. The SDK doesn't persist opt-out, so check where your app sets it at launch. |
| No request after `track()`, and no error | The SDK is waiting for the next scheduled upload. | Call `amplitude.flush()`, or wait up to 30 seconds. |

## Confirm the event in Amplitude

1. In Amplitude, open **User Lookup** and search for the device ID from `amplitude.getDeviceId()`, or for the user ID if you set one.
2. Open the **Activity** tab and turn on **Live event updates**.
3. Confirm that `Sign Up Clicked` appears with the `plan` property.

If the event doesn't appear within a minute, follow [Verify events](https://amplitude.com/docs/sdks/analytics/ios/ios-swift-sdk/verify-events). That page walks through each stage between `track()` and Amplitude's servers.

## Next steps

- Identify signed-in users with [`setUserId()`](https://amplitude.com/docs/sdks/analytics/ios/ios-swift-sdk/instrument-and-configure#set-the-user-id), and call [`reset()`](https://amplitude.com/docs/sdks/analytics/ios/ios-swift-sdk/instrument-and-configure#reset-when-a-user-logs-out) when they sign out.
- Choose which [Autocapture](https://amplitude.com/docs/sdks/analytics/ios/ios-swift-sdk/instrument-and-configure#autocapture) events to turn on.
- Add the custom events and properties your tracking plan needs. Go to [Track events](https://amplitude.com/docs/sdks/analytics/ios/ios-swift-sdk/instrument-and-configure#track-events).
- Control when and how the SDK uploads. Go to [Data delivery](https://amplitude.com/docs/sdks/analytics/ios/ios-swift-sdk/instrument-and-configure#data-delivery).