데이터 전송 프로세스

Amplitude에서의 데이터 전송 프로세스는 Native/Hybrid 영역은 각각의 SDK 탑재를 통해 진행합니다.

Hybrid 영역은 앱/웹 분기처리하지 않으며, 모든 플랫폼에 SDK를 탑재합니다.

SDK 설치

Amplitude iOS(Swift) SDK는 SPM 또는 CocoaPods로 설치할 수 있습니다.

대시보드에서 API Key 확인

Amplitude Data → Sources → iOS Source를 선택하면 Source Settings에서 API Key를 확인할 수 있습니다.

SPM 방식

• Xcode 프로젝트 → Package Manager로 Amplitude SDK 추가
• 저장소: github.com/amplitude/Amplitude-Swift

CocoaPods 방식

Podfile에 추가 후 pod install 실행

pod 'AmplitudeSwift'

초기 설정

AppDelegate의 didFinishLaunchingWithOptions에서 Amplitude를 초기화합니다.

autocapture: session, appLifecycles, screen view 등. 빈 배열 []이면 session 자동 수집을 끌 수 있습니다.

import AmplitudeSwift

let amplitude = Amplitude(configuration: Configuration(
    apiKey: AMPLITUDE_API_KEY,
    autocapture: []
))

주요 Configuration 옵션

USER ID

• SDK 연동 시 device ID가 자동 생성됩니다.
• 로그인 시 setUserId를 호출합니다.

amplitude.setUserId(userId: "로그인 사용자 식별 값")

Event

• BaseEvent로 이벤트명·eventProperties(Dictionary)를 전달합니다.

아래 코드는 샘플이며, 실제 값은 텍소노미 기획 문서 기준으로 적용하세요.

let event = BaseEvent(eventType: "텍소노미에 정의된 이벤트명")
amplitude.track(event: event)

let event = BaseEvent(
    eventType: "텍소노미에 정의된 이벤트명",
    eventProperties: [
        "텍소노미에 정의된 이벤트 속성명": "값",
        "텍소노미에 정의된 이벤트 속성명": false,
        "텍소노미에 정의된 이벤트 속성명": 42,
        "텍소노미에 정의된 이벤트 속성명": Date(),
        "텍소노미에 정의된 이벤트 속성명": ["any", "array", "here"]
    ]
)
amplitude.track(event: event)

User Property

• identify와 Identify 객체를 사용합니다.
• set, setOnce, add, append, remove, clearAll 등을 지원합니다.

아래 코드는 샘플이며, 실제 값은 텍소노미 기획 문서 기준으로 적용하세요.

Identify — set

let identify = Identify()
    .set("설정할 사용자 속성명(String)", value: "저장할 사용자 속성 값" as NSObject)
amplitude.identify(identify: identify)

Identify — setOnce / add

let identify = Identify().setOnce("설정할 사용자 속성명", value: "2015-08-24" as NSObject)
amplitude.identify(identify: identify)

let identify2 = Identify().add("설정할 사용자 속성명(Number)", value: NSNumber(value: 23)!)
amplitude.identify(identify: identify2)

Identify — append / remove / clearAll

var array: [AnyHashable] = []
array.append("Array값1")
let identify = Identify()
identify.append("설정할 사용자 속성명(Array)", value: array)!
amplitude.identify(identify: identify)

let identify2 = Identify().remove("삭제할 사용자 속성명", value: "값" as NSObject)
amplitude.identify(identify: identify2)

let identify3 = Identify()
identify3.clearAll()
amplitude.identify(identify: identify3)

Ecommerce Data

매출·구매는 Revenue 객체로, 장바구니·상품 데이터는 Cart object array로 전송합니다. Cart Analysis 차트 활용을 위해 object array 전송과 Revenue를 함께 사용하는 것을 권장합니다. (공식 — Send the cart object array)

Cart object array 전송

products와 같이 상품 목록을 담는 object array를 User Property 또는 Event Property로 전송합니다. 수집 후 Amplitude Data에서 해당 속성의 Property splitting(Type: Array, Item type: Any)을 활성화해야 Cart Analysis에서 분석할 수 있습니다.

① Identify API — set() / append()

let identify = Identify()
identify.append(
  property: "products",
  value: [
    [
      "product_id": 123,
      "sku": "41245",
      "name": "Sunscreen",
      "category": "beauty",
      "price": 12.6
    ] as [String: Any]
  ]
)
amplitude.identify(identify: identify)

② Event Property — track

let event = BaseEvent(
  eventType: "Product Viewed",
  eventProperties: [
    "products": [
      [
        "product_id": 123,
        "sku": "41245",
        "name": "Sunscreen",
        "category": "beauty",
        "price": 12.6
      ]
    ]
  ]
)
amplitude.track(event: event)

Revenue 전송

구매 이벤트 속성 (옵션)

let revenue = Revenue()
revenue.productId = "텍소노미에 정의된 상품 ID"
revenue.price = NSNumber(value: 50000)
revenue.quantity = 3
revenue.revenueType = "purchase"
amplitude.revenue(revenue: revenue)

하이브리드

WKWebView User-Agent에 네이티브 ID를 붙여 WEB SDK 초기화에 사용합니다.

let contentController = WKUserContentController()
let config = WKWebViewConfiguration()
let userID = amplitude.getUserId()
let deviceID = amplitude.getDeviceId()
let sessionID = amplitude.getSessionId()
config.applicationNameForUserAgent = "/MaxonomyiOS/\(userID)/\(deviceID)/\(sessionID)"
config.userContentController = contentController

최종 반영 예시 코드

아래는 연동 완료 시 실제 서비스에 반영되어야 하는 예시 코드 패턴입니다.

SDK 초기화뿐 아니라 User Property·Event 태깅 예시를 함께 정리했습니다.

AppDelegate — Initialize

let amplitude = Amplitude(configuration: Configuration(
    apiKey: AMPLITUDE_API_KEY,
    autocapture: []
))
amplitude.setUserId(userId: "사용자 ID")

WebView — 하이브리드 (User-Agent)

WKWebView User-Agent에 네이티브 ID를 붙여 WEB SDK 초기화에 사용합니다. (하이브리드 · WEB 가이드 참고)

let contentController = WKUserContentController()
let config = WKWebViewConfiguration()
let userID = amplitude.getUserId()
let deviceID = amplitude.getDeviceId()
let sessionID = amplitude.getSessionId()
config.applicationNameForUserAgent = "/MaxonomyiOS/\(userID)/\(deviceID)/\(sessionID)"
config.userContentController = contentController

WebView — WEB SDK 초기화 (하이브리드)

중요: WEB SDK 플러그인은 amplitude.init() 전에 등록해야 합니다. (WEB 최종 반영 예시 참고)

<script>
  try {
    if (userAgent.indexOf('MaxonomyAndroid') > -1 || userAgent.indexOf('MaxonomyiOS') > -1) {
      amplitude.init("API_KEY", {
        deviceId: UserAgent에_담긴_deviceID,
        sessionId: UserAgent에_담긴_sessionID,
        userId: UserAgent에_담긴_userID,
        autocapture: false
      });
    }
  } catch (e) {
    console.log("Hybrid Errror : " + e);
  }
</script>

User Property · Event 태깅

중요: 이벤트명·속성명·User Property 키/값은 텍소노미 기획 문서에 정의된 명세로 교체하여 적용해 주세요.

let identify = Identify()
    .set("membership_level", value: "gold" as NSObject)
    .set("country_code", value: "KR" as NSObject)
amplitude.identify(identify: identify)

let event = BaseEvent(
    eventType: "login_completed",
    eventProperties: [
        "login_method": "kakao",
        "is_first_login": false
    ]
)
amplitude.track(event: event)

UTM 태깅 (APP)

APP의 UTM 수집·집계는 Browser SDK와 동일한 원칙을 따릅니다. iOS에서는 Enrichment Plugin으로 세션 전환 시 UTM User Property를 초기화하고, 딥링크·유니버설 링크 진입 시 URL 쿼리의 UTM을 identify로 반영합니다.

1. Enrichment Plugin — 세션 시작·종료 시 UTM 초기화

앱 최초 실행 시점에 UTM 유입 여부를 항상 판단하기 어렵다는 전제에서, session_start / session_end마다 UTM 관련 User Property를 $unset으로 초기화하는 패턴을 권장합니다.

참고 고객사에서 앱 접속 시점에 UTM 유입을 스스로 판단할 수 있다면, 초기화 처리뿐만 아니라 UTM 갱신(업데이트) 로직을 함께 설계할 수 있습니다.

import AmplitudeSwift

class EnrichmentPlugin: Plugin, EventPlugin {
    let type: PluginType = .enrichment
    var amplitude: Amplitude?

    func setup(amplitude: Amplitude) {
        self.amplitude = amplitude
    }

    func execute(event: BaseEvent?) -> BaseEvent? {
        return event
    }

    func track(event: BaseEvent) -> BaseEvent? {
        if event.eventType == "session_start" || event.eventType == "session_end" {
            var userProps = event.userProperties ?? [:]
            userProps["$unset"] = [
                "utm_medium": "-",
                "utm_source": "-",
                "utm_campaign": "-",
                "utm_content": "-",
                "utm_term": "-",
                "utm_id": "-"
            ]
            event.userProperties = userProps
        }
        return event
    }

    func identify(event: IdentifyEvent) -> IdentifyEvent? { return event }
    func groupIdentify(event: GroupIdentifyEvent) -> GroupIdentifyEvent? { return event }
    func revenue(event: RevenueEvent) -> RevenueEvent? { return event }
    func flush() {}
    func onUserIdChanged(_ userId: String?) {}
    func onDeviceIdChanged(_ deviceId: String?) {}
    func onSessionIdChanged(_ sessionId: Int64) {}
    func onOptOutChanged(_ optOut: Bool) {}
}

2. Plugin 등록

AppDelegate 등 앱 실행 진입점에서 Amplitude SDK 초기화 직후 Plugin을 등록합니다.

amplitude.add(plugin: EnrichmentPlugin())

3. 일반 딥링크 — UTM 태깅

커스텀 URL 스킴·딥링크 URL의 쿼리에 UTM이 있으면 identify로 반영합니다. 최초 유입 값은 setOnce로 initial_*에 보존합니다.

func application(
    _ app: UIApplication,
    open url: URL,
    options: [UIApplication.OpenURLOptionsKey: Any] = [:]
) -> Bool {
    guard let query = url.query else { return false }

    let utmKeys = ["utm_source", "utm_medium", "utm_campaign", "utm_content", "utm_term", "utm_id"]
    let identify = Identify()
    var hasUTMData = false

    for item in query.components(separatedBy: "&") {
        let pair = item.split(separator: "=", maxSplits: 1).map(String.init)
        guard pair.count == 2 else { continue }
        let key = pair[0]
        let value = pair[1]
        guard utmKeys.contains(key) else { continue }
        identify.set(property: key, value: value)
        identify.setOnce(property: "initial_\(key)", value: value)
        hasUTMData = true
    }

    if hasUTMData {
        amplitude.identify(identify: identify)
    }
    return true
}

UTM이 없고 세션이 변경된 경우 Browser SDK와 같이 EMPTY 등으로 초기화하는 로직이 필요하면, UserDefaults에 세션 ID를 저장해 비교하는 방식을 추가로 검토하세요.

4. 유니버설 링크 — UTM 태깅

NSUserActivityTypeBrowsingWeb 유니버설 링크 진입 시 쿼리 파라미터를 동일하게 처리합니다.

func application(
    _ application: UIApplication,
    continue userActivity: NSUserActivity,
    restorationHandler: @escaping ([UIUserActivityRestoring]?) -> Void
) -> Bool {
    guard userActivity.activityType == NSUserActivityTypeBrowsingWeb,
          let incomingURL = userActivity.webpageURL,
          let components = URLComponents(url: incomingURL, resolvingAgainstBaseURL: true),
          let queryItems = components.queryItems else {
        return false
    }

    let utmKeys = ["utm_source", "utm_medium", "utm_campaign", "utm_content", "utm_term", "utm_id"]
    let identify = Identify()
    var hasUTMData = false

    for item in queryItems {
        guard utmKeys.contains(item.name), let value = item.value else { continue }
        identify.set(property: item.name, value: value)
        identify.setOnce(property: "initial_\(item.name)", value: value)
        hasUTMData = true
    }

    if hasUTMData {
        amplitude.identify(identify: identify)
    }
    return true
}

추가 설정 항목

Amplitude에 한 번 연동된 이후, SDK를 통해 추가 설정을 적용할 수 있습니다.

1. 세션 길이 조정

앱이 백그라운드로 전환된 뒤 세션이 종료되기까지의 대기 시간(minTimeBetweenSessionsMillis)을 조정하는 설정입니다. WEB과 APP의 세션 주기·타임아웃이 서로 다를 때, 네이티브 앱 기준으로 세션 길이를 맞추기 위해 사용할 수 있습니다.

let amplitude = Amplitude(
    configuration: Configuration(
        apiKey: AMPLITUDE_API_KEY,
        minTimeBetweenSessionsMillis: 1000
    )
)

2. Device ID 설정 (Braze 연동)

Amplitude deviceId를 Braze device ID와 동일하게 맞추는 코드입니다. Braze를 함께 사용하는 경우 크로스 분석·동일 사용자 매칭에 활용합니다.

amplitude.setDeviceId(deviceId: NSUUID().uuidString)
// Braze를 사용하는 고객사라면 크로스 분석을 위해 Braze device ID로 설정하는 것을 권장드립니다.
if let brazeDeviceId = AppDelegate.braze?.getDeviceId() {
    amplitude.setDeviceId(deviceId: brazeDeviceId)
}

3. Device ID 조회

현재 Amplitude SDK에 설정된 Device ID를 가져오는 코드입니다.

let deviceId = amplitude.getDeviceId()

4. Session ID 조회

현재 Amplitude SDK의 Session ID를 가져오는 코드입니다.

let sessionId = amplitude.getSessionId()

Group

Amplitude Group은 사용자(userId)를 회사·계정·조직 등 그룹 단위로 묶어 분석할 때 사용하는 기능입니다. B2B·멀티 테넌트 서비스처럼 “어떤 고객사(그룹) 소속 사용자가 어떻게 행동하는지”를 보고 싶을 때 활용합니다.

• 한 사용자는 여러 Group에 동시에 속할 수 있습니다.
• setGroup으로 사용자를 그룹에 연결하고, groupIdentify로 그룹 단위 속성(Group Property)을 설정합니다.
• 이벤트·User Property와 별도로, 그룹 수준의 속성·코호트 분석이 가능합니다.

Group 연결 — setGroup

현재 사용자를 지정한 그룹 타입(groupType)·그룹명(groupName)에 연결합니다. 이후 해당 사용자의 이벤트는 그 Group과 함께 집계·분석됩니다.

amplitude.setGroup(groupType: "그룹타입", groupName: "그룹명")

Group Property — groupIdentify

특정 Group에 대한 속성 값(예: 구독일, 플랜 등)을 설정하는 API입니다. User Property의 identify와 유사하지만, 대상이 그룹입니다.

let groupType = "그룹타입"
let groupName = "그룹명"
let identify = Identify().set(property: "subscribe_date", value: "2026-04-20")
amplitude.groupIdentify(groupType: groupType, groupName: groupName, identify: identify)

Session Replay

Amplitude에서는 Session Replay 기능을 제공합니다.

• Session Replay는 세션 동안 수집된 이벤트를 기반으로, 대시보드에서 앱 화면에서의 사용자 행동을 재생해 보여줍니다.
• iOS 앱에서 사용하려면 대시보드에서 기능을 활성화한 뒤, Session Replay 패키지를 설치하고 플러그인을 연동해야 합니다.

Amplitude 대시보드 → Settings → Session Replay & Heatmap 경로에서 기능 활성화가 가능합니다.

SPM 방식

Xcode → File → Add Package Dependencies에서 아래 저장소를 추가합니다.

https://github.com/amplitude/AmplitudeSessionReplay-iOS

CocoaPods 방식

Podfile에 추가 후 pod install을 실행합니다.

pod 'AmplitudeSessionReplay'
pod 'AmplitudeSwiftSessionReplayPlugin'

연동 코드

Amplitude 초기화 후 AmplitudeSwiftSessionReplayPlugin을 등록합니다. sampleRate는 세션 녹화 비율, captureWebViews는 WebView 리플레이 호환 설정입니다.

import AmplitudeSwift
import AmplitudeSwiftSessionReplayPlugin

let amplitude = Amplitude(configuration: Configuration(apiKey: API_KEY))

// 세션 비율 & 웹뷰 리플레이 호환 설정
amplitude.add(plugin: AmplitudeSwiftSessionReplayPlugin(
    sampleRate: 1.0,
    captureWebViews: true
))

연동 체크리스트

배포 전 아래 항목을 확인하세요. (데이터 검수는 대시보드 Live View·User Lookup을 사용합니다.)

• SPM/CocoaPods로 SDK가 설치되고, 앱 시작 시 Amplitude SDK가 1회만 초기화되는가
• 프로젝트 API Key가 운영/개발 환경별로 분리되어 있는가
• 로그인 시 setUserId 및 필요 시 identify가 호출되는가
• Taxonomy(이벤트·속성명)와 코드의 track 이벤트명이 일치하는가
• Revenue·Ecommerce Data(Cart object array) 속성이 기획과 일치하는가
• 하이브리드 WKWebView에서 User-Agent 설정 및 WEB SDK 이중 수집이 없는가
• Group 기능 사용 시 setGroup·groupIdentify 연동이 완료되었는가 (유료 기능)
• Session Replay 사용 시 대시보드(Settings → Session Replay & Heatmap) 활성화 및 SDK 플러그인 연동이 완료되었는가
• 배포 전 Live View·User Lookup에서 이벤트·유저 속성이 기대대로 수집되는지 확인했는가