--- title: Get started with the Unified SDK for Swift description: "Install the Amplitude Unified SDK for Swift, initialize Analytics, Feature Experiment, and Session Replay with one initializer, and send a first event." product: analytics lang: en last_updated: 2026-11-05 token_estimate: 3211 --- # Get started with the Unified SDK for Swift - **Package:** `AmplitudeUnified` ([cocoapods](https://cocoapods.org/pods/AmplitudeUnified)) - **Latest version:** 0.0.4 This guide shows how to install the Unified SDK for Swift (`AmplitudeUnified`), initialize every product it includes with one initializer, and send one custom event to Amplitude. For the full option list, go to [AnalyticsConfig](https://amplitude.com/docs/sdks/analytics/ios/unified-sdk/reference#analyticsconfig). For changes between versions, go to the [`AmplitudeUnified` changelog](https://github.com/amplitude/AmplitudeUnified-Swift/blob/main/CHANGELOG.md). > 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 Unified SDK bundles the [iOS Swift SDK](https://amplitude.com/docs/sdks/analytics/ios/ios-swift-sdk/get-started) (`AmplitudeSwift`) with [Feature Experiment](https://amplitude.com/docs/sdks/experiment-sdks/experiment-ios) and, on iOS only, [Session Replay](https://amplitude.com/docs/sdks/session-replay/session-replay-ios-plugin). Every analytics method works the same as in the iOS Swift SDK. If you need Analytics only, install the iOS Swift SDK instead. 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. To find the key, go to _Settings > Projects_, select your project, and open _General_. - The data center your organization uses: US (default) or EU. - Xcode 16.3 or later, which the bundled iOS Swift SDK requires. - A deployment target of at least iOS 15.0, macOS 12, tvOS 15, watchOS 9, or visionOS 1.0 when you install with Swift Package Manager in Xcode 27 or later (Swift 6.4). Older Xcode versions and CocoaPods accept iOS 13.0, macOS 10.15, tvOS 13.0, and watchOS 7.0. ## Install the SDK #### Swift Package Manager 1. In Xcode, select _File > Add Package Dependencies_. 2. Enter `https://github.com/amplitude/AmplitudeUnified-Swift` in the search field. 3. Set **Dependency Rule** to **Up to Next Minor Version**, starting from `0.0.4`. 4. Select **Add Package**, then add the `AmplitudeUnified` product to your app target. To add the SDK to a `Package.swift` manifest instead: ```swift dependencies: [ .package(url: "https://github.com/amplitude/AmplitudeUnified-Swift", from: "0.0.4"), ], targets: [ .target( name: "MyApp", dependencies: [.product(name: "AmplitudeUnified", package: "AmplitudeUnified-Swift")] ), ] ``` #### CocoaPods 1. Add the pod to your `Podfile`: ```ruby pod 'AmplitudeUnified', '~> 0.0.4' ``` 2. Run `pod install`, then open the `.xcworkspace` file that CocoaPods creates. The package depends on `AmplitudeSwift` 1.17.0 or later, `AmplitudeExperiment` 1.19.0 or later, and, on iOS, `AmplitudeSessionReplay` 0.8.0 or later, all below 2.0.0. Your package manager resolves the newest versions in those ranges. ### Fix installation problems | Symptom | Cause | Fix | | --- | --- | --- | | `No such module 'AmplitudeUnified'` | The target that imports the SDK doesn't link the `AmplitudeUnified` product, or CocoaPods users opened `.xcodeproj`. | Add `AmplitudeUnified` under the target's **Frameworks, Libraries, and Embedded Content**. With CocoaPods, open the `.xcworkspace`. | | Swift Package Manager reports that the package requires a newer platform | Xcode 27 reads the package's Swift 6.4 manifest, which requires iOS 15.0. | Raise the app's deployment target to iOS 15.0 or later. | | Duplicate Amplitude symbols, or events sent twice | The app links `AmplitudeUnified` and also adds `AmplitudeSwift`, `AmplitudeExperiment`, or `AmplitudeSessionReplay` itself. | Remove the individual packages. The Unified SDK brings them in. | ## Initialize the SDK Create one `Amplitude` instance when your app launches, and keep a strong reference to it, for example as a property of your `App` struct or `AppDelegate`. The Unified initializer creates Analytics, then adds the Session Replay plugin (iOS only) and the Feature Experiment plugin. #### Swift ```swift import AmplitudeUnified let amplitude = Amplitude( apiKey: "YOUR_API_KEY", serverZone: .EU, // Omit for US projects. sessionReplayConfig: SessionReplayPlugin.Config(sampleRate: 1.0) // Records every session. Lower this before production. ) ``` `import AmplitudeUnified` also makes `AmplitudeSwift`, Experiment, and Session Replay types available. You don't need to import them separately. #### Objective-C ```objc @import AmplitudeUnified; @import Experiment; // With CocoaPods: @import AmplitudeExperiment; @import AmplitudeSessionReplay; AMPSessionReplayPluginConfig *sessionReplayConfig = [[AMPSessionReplayPluginConfig alloc] initWithSampleRate:1.0 maskLevel:MaskLevelMedium quality:AMPSessionReplayQualityProfileHigh enableRemoteConfig:YES webviewMappings:@{} autoStart:YES captureWebViews:NO recordLogOptions:[[RecordLogOptions alloc] initWithLogCountThreshold:1000 maxMessageLength:2000] uploadConfig:[[AMPSessionReplayUploadConfig alloc] initWithDisableMeteredUploads:NO]]; Amplitude *amplitude = [[Amplitude alloc] initWithApiKey:@"YOUR_API_KEY" serverZone:AMPServerZoneEU instanceName:@"$default_instance" analyticsConfig:[[AMPAnalyticsConfig alloc] init] experimentConfig:[[ExperimentPluginConfig alloc] init] sessionReplayConfig:sessionReplayConfig logger:nil]; ``` Import the Experiment and Session Replay modules as well as `AmplitudeUnified`. Without those imports, Objective-C sees the Experiment, Session Replay, and server zone types only as forward declarations. Session Replay records nothing until you set `sampleRate` above its default of `0`. With the defaults, `Amplitude(apiKey:)` sets up Session Replay but never records. ### Fix initialization problems | Symptom | Cause | Fix | | --- | --- | --- | | No replays, and events have no `[Amplitude] Session Replay ID` property | `sampleRate` is `0.0`, the default. | Pass `SessionReplayPlugin.Config(sampleRate:)` with a value above `0`. | | Objective-C: EU project, but events reach the US data center or fail with `Invalid API key` | In version 0.0.4, `initWithApiKey:serverZone:` ignores its `serverZone` argument. | Use the full initializer, as the Objective-C example shows. | | Objective-C: `no visible @interface for 'Amplitude' declares the selector 'initWithApiKey:analyticsConfig:'` | Objective-C has only three initializers. It has no shorter forms that take one config object. | Use the full initializer and pass defaults for the configs you don't change. Go to [Objective-C initializers](https://amplitude.com/docs/sdks/analytics/ios/unified-sdk/reference#objective-c-initializers). | | Swift: `argument '...' must precede argument '...'` | Swift requires `AnalyticsConfig` and `ExperimentPlugin.Config` arguments in their declared order. | Reorder the arguments to match [AnalyticsConfig](https://amplitude.com/docs/sdks/analytics/ios/unified-sdk/reference#analyticsconfig) or [ExperimentPlugin.Config](https://amplitude.com/docs/sdks/analytics/ios/unified-sdk/reference#experimentpluginconfig). | | Log: `Warn: [SessionReplay] Remote Config unavailable; keeping the current targeting state.` | Session Replay couldn't fetch its remote configuration, often because the API key or `serverZone` is wrong. | Check the API key and `serverZone`. | | Events never upload | The instance was a local variable, and Swift released it when the function returned. | Store the instance in a property or singleton that lives as long as the app. | ## Send a first event Track one custom event, then call `flush()` to upload it right away. To see the result, pass a `callback` in `AnalyticsConfig`. The SDK calls the callback once for each event after the upload finishes. #### Swift ```swift let amplitude = Amplitude( apiKey: "YOUR_API_KEY", analyticsConfig: AnalyticsConfig(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 AMPAnalyticsConfig *analyticsConfig = [[AMPAnalyticsConfig alloc] init]; analyticsConfig.callback = ^(AMPBaseEvent *event, NSInteger code, NSString *message) { NSLog(@"%@ %ld %@", event.eventType, (long)code, message); }; Amplitude *amplitude = [[Amplitude alloc] initWithApiKey:@"YOUR_API_KEY" serverZone:AMPServerZoneUS instanceName:@"$default_instance" analyticsConfig:analyticsConfig experimentConfig:[[ExperimentPluginConfig alloc] init] sessionReplayConfig:[[AMPSessionReplayPluginConfig alloc] initWithSampleRate:0 maskLevel:MaskLevelMedium quality:AMPSessionReplayQualityProfileHigh enableRemoteConfig:YES webviewMappings:@{} autoStart:YES captureWebViews:NO recordLogOptions:[[RecordLogOptions alloc] initWithLogCountThreshold:1000 maxMessageLength:2000] uploadConfig:[[AMPSessionReplayUploadConfig alloc] initWithDisableMeteredUploads:NO]] logger:nil]; [amplitude track:@"Sign Up Clicked" eventProperties:@{@"plan": @"starter"}]; [amplitude flush]; // Sign Up Clicked 200 Successfully send event ``` On a first launch, the callback prints a `session_start` line before `Sign Up Clicked`, because the SDK tracks sessions by default. Without `flush()`, the SDK uploads queued events every 30 seconds, when the queue reaches 30 events, or when the app moves to the background. Remove the `flush()` call after you confirm the setup. ### Fix upload problems The Unified SDK uploads events through the bundled iOS Swift SDK, so the callback codes, messages, and upload logs match the iOS Swift SDK. For every code and log line, go to [Fix upload problems](https://amplitude.com/docs/sdks/analytics/ios/ios-swift-sdk/get-started#fix-upload-problems) in the iOS Swift SDK. ## Confirm the event in Amplitude 1. In Amplitude, open **User Lookup** and search for the device ID from `amplitude.getDeviceId()`. 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/unified-sdk/verify-events). ## Next steps - Set options for each product. Go to [Configure each product](https://amplitude.com/docs/sdks/analytics/ios/unified-sdk/instrument-and-configure#configure-each-product). - Fetch flags and read variants. Go to [Use Feature Experiment](https://amplitude.com/docs/sdks/analytics/ios/unified-sdk/instrument-and-configure#use-feature-experiment). - Choose a Session Replay sample rate. Go to [Use Session Replay](https://amplitude.com/docs/sdks/analytics/ios/unified-sdk/instrument-and-configure#use-session-replay). - Track custom events, identify users, and choose autocapture events. Go to [Instrument and configure the iOS Swift SDK](https://amplitude.com/docs/sdks/analytics/ios/ios-swift-sdk/instrument-and-configure).