Get started with the iOS Swift SDK

cocoapodsv1.19.4

For iOS, macOS, tvOS, watchOS, and visionOS developers10 minBeginner

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. For changes between versions, go to the iOS Swift SDK release notes.

The iOS Swift SDK is the analytics-only package. If you also need Session Replay or Feature Experiment, install the Unified SDK for Swift (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.

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 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.

In Xcode, select File > Add Package Dependencies.
Enter https://github.com/amplitude/Amplitude-Swift in the search field.
Set Dependency Rule to Up to Next Major Version, starting from 1.19.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")]
    ),
]

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

import AmplitudeSwift

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

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

swift

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

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.

Swift requires Configuration arguments in their declared order. If Xcode reports an argument order error, check the order in 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.
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

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

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.
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

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

If the event doesn't appear within a minute, follow Verify events. That page walks through each stage between track() and Amplitude's servers.

Next steps

Identify signed-in users with setUserId(), and call reset() when they sign out.
Choose which Autocapture events to turn on.
Add the custom events and properties your tracking plan needs. Go to Track events.
Control when and how the SDK uploads. Go to Data delivery.

Was this helpful?