Get started with the Unified SDK for Swift

cocoapodsv0.0.4

이 페이지는 아직 귀하의 언어로 번역되지 않았습니다. 현재 작업 중이므로 곧 다시 확인해 주십시오.

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

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. For changes between versions, go to the AmplitudeUnified changelog.

The Unified SDK bundles the iOS Swift SDK (AmplitudeSwift) with Feature Experiment and, on iOS only, Session Replay. 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.

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

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

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

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.

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.
Swift: `argument '...' must precede argument '...'`	Swift requires `AnalyticsConfig` and `ExperimentPlugin.Config` arguments in their declared order.	Reorder the arguments to match AnalyticsConfig or ExperimentPlugin.Config.
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

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

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 in the iOS Swift SDK.

Confirm the event in Amplitude

In Amplitude, open User Lookup and search for the device ID from amplitude.getDeviceId().
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.

Next steps

Set options for each product. Go to Configure each product.
Fetch flags and read variants. Go to Use Feature Experiment.
Choose a Session Replay sample rate. Go to Use Session Replay.
Track custom events, identify users, and choose autocapture events. Go to Instrument and configure the iOS Swift SDK.

이 내용이 도움이 되었나요?