Swift용 통합 SDK

이 문서는 Amplitude Unified SDK for Swift에 대한 공식 문서입니다.

통합 SDK는 Amplitude의 기존 SDK를 감싸고 여러 Amplitude 제품을 함께 사용할 수 있는 간소화된 인터페이스를 제공합니다. 다음이 포함됩니다.

SDK 설치

Podfile에 종속성을 추가하십시오.
bash
```
pod 'AmplitudeUnified', '~> 0.0.3'
```
프로젝트 디렉토리에서 pod install을 실행하십시오.

SDK 초기화

계측하기 전에 SDK를 초기화하십시오. Amplitude 프로젝트에 대한 API 키를 제공하십시오.

// Basic initialization with default configurations
let amplitude = Amplitude(
    apiKey: "YOUR_API_KEY"
)
// Advanced initialization with custom configurations
let amplitude = Amplitude(
    apiKey: "YOUR_API_KEY",
    serverZone: .US,
    instanceName: "default_instance",
    analyticsConfig: AnalyticsConfig(),
    experimentConfig: ExperimentPlugin.Config(),
    sessionReplayConfig: SessionReplayPlugin.Config(),
    logger: ConsoleLogger()
)

SDK 구성

분석 구성

Unified SDK는 분석 구성 객체를 사용합니다. 구성에 대한 자세한 내용은 분석 SDK 문서를 참조하세요.

let analyticsConfig = AnalyticsConfig(
    flushQueueSize: 30,
    flushIntervalMillis: 30000,
    trackingOptions: TrackingOptions().disableTrackCity().disableTrackIpAddress(),
    minTimeBetweenSessionsMillis: 300000,
    autocapture: [.sessions, .appLifecycles, .screenViews]
)
let amplitude = Amplitude(
    apiKey: "YOUR_API_KEY",
    analyticsConfig: analyticsConfig
)

실험 구성

통합 SDK는 실험 구성 객체를 허용합니다. 구성 세부 사항은 실험 SDK 문서를 참조하십시오.

let experimentConfig = ExperimentPlugin.Config(
    serverUrl: "https://api.lab.amplitude.com",
    debug: true,
    fetchTimeoutMillis: 10000
)
let amplitude = Amplitude(
    apiKey: "YOUR_API_KEY",
    experimentConfig: experimentConfig
)

세션 리플레이 구성

통합 SDK는 세션 리플레이 SDK를 합리적인 기본값으로 구성합니다. 더 고급옵션 구성 옵션에 대해서는 세션 리플레이 SDK 문서를 참조하십시오.

세션 리플레이는 iOS에서만 사용할 수 있으며 macOS, tvOS, watchOS 또는 visionOS에서는 사용할 수 없습니다.

#if canImport(AmplitudeSessionReplay)
let sessionReplayConfig = SessionReplayPlugin.Config(
    sampleRate: 1.0
)
let amplitude = Amplitude(
    apiKey: "YOUR_API_KEY",
    sessionReplayConfig: sessionReplayConfig
)
#endif

SDK 사용

통합 SDK는 단일 인터페이스를 통해 개별 SDK의 모든 기능에 액세스할 수 있도록 해줍니다.

분석

통합 SDK는 모든 분석 SDK 기능을 직접 제공합니다. 메서드의 전체 목록은 분석 SDK 문서를 참조하십시오.

// Track an event
amplitude.track(eventType: "Button Clicked", eventProperties: ["button_id": "sign_up"])
// Set user properties
let identify = Identify()
identify.set(property: "plan", value: "premium")
amplitude.identify(identify: identify)
// Set user ID
amplitude.setUserId(userId: "user@example.com")

실험

통합 SDK는 Amplitude 인스턴스를 생성할 때 실험 SDK를 초기화하고 구성합니다.experiment 속성을 통해 실험 클라이언트에 액세스하십시오.

// Fetch variants for the current user
guard let experiment = amplitude.experiment else {
    return
}
experiment.fetch(user: nil) { experiment, error in
    if let error = error {
        print("Error fetching variants: \(error)")
        return
    }
    // Get a variant for a flag
    let variant = experiment.variant("my-flag")
    print("Variant: \(variant.value)")
    // Evaluate a flag locally
    let localVariant = experiment.variant("local-flag", fallback: Variant("default"))
    print("Local variant: \(localVariant.value)")
    // Exposure tracking is automatic when you call variant()
    // But you can also track exposures manually
    experiment.exposure(key: "my-flag")
}

세션 리플레이

통합 SDK는 iOS에서 Amplitude 인스턴스를 생성할 때 세션 리플레이 SDK를 초기화하고 구성합니다. 세션 리플레이는 macOS, tvOS, watchOS 또는 visionOS에서 사용할 수 없습니다.

#if canImport(AmplitudeSessionReplay)
// Session Replay is automatically initialized and configured.
// Access the Session Replay client through the sessionReplay property.
// Start (or resume) capture
amplitude.sessionReplay?.start()
// Stop (pause) capture. Call start() again to resume; both methods act on the same instance.
amplitude.sessionReplay?.stop()
#endif

고급옵션 항목

이 섹션의 지침에 따라 ID 관리 및 기타 기능을 활성화하십시오.

ID 관리

통합 SDK는 모든 Amplitude 제품에서 사용자 ID를 동기화하는 통합 ID 관리 시스템을 제공합니다. Amplitude 메서드를 사용하여 사용자 ID 또는 기기 ID를 설정하면 SDK는 변경 사항을 실험 및 세션 리플레이에 전파합니다.

// Set user ID - automatically propagated to all products
amplitude.setUserId(userId: "user@example.com")
// Set device ID - automatically propagated to all products
amplitude.setDeviceId(deviceId: "custom-device-id")
// Reset user - clears user ID and generates a new device ID
amplitude.reset()
// Access the current identity
let userId = amplitude.identity.userId
let deviceId = amplitude.identity.deviceId

사용자 속성

통합 SDK는 identify 작업으로 설정된 사용자 속성의 캐시를 유지합니다. 캐시를 사용하면 전체 시간에 현재 사용자 속성 상태에 액세스할 수 있습니다.

// Set user properties
let identify = Identify()
identify.set(property: "plan", value: "premium")
identify.set(property: "age", value: 25)
amplitude.identify(identify: identify)
// Access the current user properties
let userProperties = amplitude.identity.userProperties
print("User plan: \(userProperties["plan"] ?? "none")")
print("User age: \(userProperties["age"] ?? 0)")
// Clear all user properties
let clearIdentify = Identify()
clearIdentify.clearAll()
amplitude.identify(identify: clearIdentify)

디버깅

디버그 로깅을 활성화하려면 분석 구성에서 로그 수준을 DEBUG로 설정하십시오.

let analyticsConfig = AnalyticsConfig(
    // Other configuration options...
)
let amplitude = Amplitude(
    apiKey: "YOUR_API_KEY",
    analyticsConfig: analyticsConfig,
    logger: ConsoleLogger(logLevel: LogLevelEnum.debug.rawValue)
)

일반적인 문제

통합 SDK 구현이 예상대로 작동하지 않는 경우 다음과 같은 일반적인 문제를 계정하십시오.

세션 리플레이는 iOS 이외의 플랫폼에서 작동하지 않습니다

세션 리플레이는 iOS에서만 사용할 수 있습니다. 이 기능은 macOS, tvOS, watchOS 또는 visionOS에서 사용할 수 없습니다. 통합 SDK는 플랫폼을 감지하고 iOS에서만 세션 리플레이를 초기화합니다.

이벤트가 Amplitude에 나타나지 않습니다.

이벤트가 Amplitude에 나타나지 않는 경우:

올바른 API 키를 사용하고 있는지 확인하십시오.
장치가 인터넷에 연결되어 있는지 확인하십시오.
이벤트가 플러시될 때까지 충분히 기다립니다(기본 시간은 30초).
로그에서 오류 메시지를 확인하십시오.

실험 플래그가 로드되지 않습니다

실험 플래그를 가져오지 못하는 경우:

amplitude.experiment이 nil가 아닌지 확인한 다음 fetch(user:completion:)을 호출하세요.
사용자 ID 또는 장치 ID가 올바르게 설정되었는지 확인하십시오.
Amplitude 실험 대시보드에서 플래그를 올바르게 구성했는지 확인하십시오.
실험 SDK의 오류 메시지가 있는지 로그에서 확인하십시오.

마이그레이션 가이드

개별 Amplitude SDK를 별도로 사용하는 경우 다음 단계에 따라 통합 SDK로 마이그레이션하십시오.

통합 SDK 종속성을 프로젝트에 추가합니다.
개별 SDK 종속성(AmplitudeSwift, 실험, AmplitudeSessionReplay)을 제거합니다.
초기화 코드를 통합 SDK 초기화로 바꿉니다.
통합 SDK 인터페이스를 사용하도록 API 호출을 업데이트하십시오.

마이그레이션 전

// Analytics SDK
let amplitude = Amplitude(configuration: Configuration(
    apiKey: "YOUR_API_KEY",
    flushQueueSize: 30,
    flushIntervalMillis: 30000
))
// Experiment SDK
let experimentClient = Experiment.initialize(
    apiKey: "YOUR_API_KEY",
    config: ExperimentConfigBuilder()
        .serverUrl("https://api.lab.amplitude.com")
        .build()
)
// Session Replay SDK
let sessionReplay = SessionReplayPlugin(config: SessionReplayPlugin.Config(
    sampleRate: 1.0
))
amplitude.add(plugin: sessionReplay)

마이그레이션 후

let analyticsConfig = AnalyticsConfig(
    flushQueueSize: 30,
    flushIntervalMillis: 30000
)
let experimentConfig = ExperimentPlugin.Config(
    serverUrl: "https://api.lab.amplitude.com"
)
let sessionReplayConfig = SessionReplayPlugin.Config(
    sampleRate: 1.0
)
let amplitude = Amplitude(
    apiKey: "YOUR_API_KEY",
    analyticsConfig: analyticsConfig,
    experimentConfig: experimentConfig,
    sessionReplayConfig: sessionReplayConfig
)

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