iOS Swift SDK

이 문서는 Amplitude 애널리틱스 iOS SDK에 대한 공식 문서입니다.

SDK 설치

SDK 초기화

이벤트를 계측하기 전에 SDK를 초기화하십시오. Amplitude 프로젝트에 대한 API 키가 필요합니다.

let amplitude = Amplitude(configuration: Configuration(
    apiKey: AMPLITUDE_API_KEY,
    autocapture: .all
))

SDK 구성

이벤트 추적

이벤트는 사용자가 애플리케이션과 상호 작용하는 방식을 나타냅니다. 예를 들어, "버튼 클릭됨"은 추적하고자 하는 작업이 될 수 있습니다.

let event = BaseEvent(
    eventType: "Button Clicked",
    eventProperties: ["my event prop key": "my event prop value"]
)
amplitude.track(event: event)

기본 추적 이벤트를 계측하는 또 다른 방법은 다음과 같습니다.

amplitude.track(
    eventType: "Button Clicked",
    eventProperties: ["my event prop key": "my event prop value"]
)

Identify

Identify 는 전체 이벤트를 전송하지 않고 특정 사용자의 사용자 속성을 설정합니다. SDK는 개별 사용자 속성에 대한 set, setOnce, unset, add, append, prepend, preInsert, postInsert, remove 및 clearAll 작업을 지원합니다. 제공된 Identify 인터페이스를 통해 작업을 선언합니다. 단일 Identify 객체에서 여러 작업을 체인화할 수 있습니다. 그런 다음 Identify 객체를 Amplitude 클라이언트에 전달하여 서버로 전송합니다.

identify 메소드를 사용하여 사용자의 ID를 처리할 수 있습니다. 이러한 방법을 적절하게 사용하면 이벤트가 장치, 브라우저 및 기타 플랫폼 간에 이동할 때 올바른 사용자에게 연결될 수 있습니다. 해당 사용자 속성 작업이 포함된 identify 호출을 Amplitude 서버로 전송하여 사용자의 이벤트를 특정 사용자 속성과 연결합니다.

let identify = Identify()
identify.set(property: "color", value: "green")
amplitude.identify(identify: identify)

모든 사용자 속성 지우기

사용자의 모든 사용자 속성을 제거하려면 clearAll을 사용하십시오. 이 작업은 되돌릴 수 없으므로 clearAll주의해서 사용하십시오.

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

자동 캡처

v1.8.0 릴리스부터 SDK는 수동 계측 없이 더 많은 이벤트를 추적할 수 있습니다. 다음 이벤트를 자동으로 추적하도록 SDK를 구성하십시오.

• 세션
• 애플리케이션 수명주기
• 화면 보기
• 요소 상호 작용
• 불만스러운 상호 작용
  • 레이지 클릭
  • 데드 클릭
• 네트워크 요청

Amplitude를 구성하여 자동 캡처 이벤트 추적을 시작할 수 있습니다. 그렇지 않으면 구성을 생략하여 세션 추적만 활성화된 상태로 유지할 수 있습니다.

let amplitude = Amplitude(configuration: Configuration(
    apiKey: "API_KEY",
    autocapture: [.sessions, .appLifecycles, .screenViews, .networkTracking]
))

let amplitude = Amplitude(configuration: Configuration(
    apiKey: "API_KEY",
    autocapture: .appLifecycles 	// or use `[]` to disable Autocapture.
))

자동 캡처를 위한 원격 구성

릴리스 v1.10.0부터 SDK는 자동 캡처 설정을 위한 원격 구성을 지원합니다. 이 기능을 사용하면 앱을 업데이트할 필요 없이 초기화 후 자동 캡처 설정을 업데이트할 수 있습니다.

기본적으로 Amplitude는 자동 캡처를 위한 원격 구성을 활성화합니다. 이 기능을 비활성화하려면 구성에서 enableAutoCaptureRemoteConfig을 false로 설정하십시오.

let amplitude = Amplitude(configuration: Configuration(
    apiKey: "API_KEY",
    autocapture: [.sessions, .appLifecycles, .screenViews],
    enableAutoCaptureRemoteConfig: false
))

원격 구성을 활성화하면 SDK가 프로젝트의 자동 캡처 설정에 대한 업데이트를 확인합니다. SDK가 업데이트를 발견하면 IT가 이를 자동으로 적용합니다. 이를 통해 다음과 같은 작업을 수행할 수 있습니다.

• 특정 자동 캡처 기능을 원격으로 활성화하거나 비활성화합니다.
• 사용자가 앱을 업데이트할 필요 없이 자동 캡처 설정을 변경할 수 있습니다.

원격 구성을 통해 이루어진 변경 사항은 향후 이벤트에 영향을 미치며 Amplitude가 이미 추적한 이벤트에는 적용되지 않습니다.

세션 추적

Amplitude는 기본적으로 세션 추적을 활성화합니다. AutocaptureOptions.sessions을 autocapture 구성에 포함하여 SDK가 세션 이벤트를 추적하도록 명시적으로 구성하거나, 다른 자동 캡처 구성과 함께 세션 이벤트 트래킹을 활성화할 수 있습니다.

let amplitude = Amplitude(configuration: Configuration(
    apiKey: "API_KEY",
    autocapture: .sessions
))

세션 추적에 대한 자세한 내용은 사용자 세션을 참조하십시오.

애플리케이션 수명주기 추적

Amplitude가 애플리케이션 생애주기 분석 이벤트를 추적할 수 있도록 하려면 AutocaptureOptions.appLifecycles을 autocapture구성에 포함하십시오.

let amplitude = Amplitude(configuration: Configuration(
    apiKey: "API_KEY",
    autocapture: .appLifecycles
))

이 설정을 활성화하면 Amplitude는 다음 이벤트를 추적합니다.

• [Amplitude] Application Installed: 이 이벤트는 사용자가 설치 후 처음으로 애플리케이션을 열 때 내부적으로 UIApplicationDidFinishLaunchingNotification 알림을 관찰하여 발생합니다.
• [Amplitude] Application Updated: 이 이벤트는 사용자가 애플리케이션 업데이트 후 애플리케이션을 열 때 내부적으로 UIApplicationDidFinishLaunchingNotification 알림을 관찰하여 발생합니다.
• [Amplitude] Application Opened: 이 이벤트는 사용자가 애플리케이션을 처음 연 이후에 실행하거나 포그라운드로 전환할 때 내부적으로 UIApplicationDidFinishLaunchingNotification 또는 UIApplicationWillEnterForegroundNotification 알림을 관찰하여 발생합니다.
• [Amplitude] Application Backgrounded: 이 이벤트는 사용자가 애플리케이션을 백그라운드로 전환할 때 내부적으로 UIApplicationDidEnterBackgroundNotification 알림을 관찰하여 발생합니다.

화면 뷰 추적

Amplitude가 화면 뷰 이벤트를 추적하도록 하려면 AutocaptureOptions.screenViews을 autocapture 설정에 포함하십시오.

// UIKit
let amplitude = Amplitude(configuration: Configuration(
    apiKey: "API_KEY",
    autocapture: .screenViews
))
// Swift UI
let amplitude = Amplitude(configuration: Configuration(
    apiKey: "API_KEY",
    autocapture: []
))
amplitude.track(ScreenViewedEvent(screenName: "Screen Name"))

이 설정을 활성화하면 Amplitude는 [Amplitude] Screen Viewed 이벤트를 추적하고 이 이벤트의 screen name 속성을 최상위 뷰 컨트롤러의 클래스 이름으로 설정합니다. Amplitude는 컨트롤러 클래스 메타데이터 viewDidAppear 메서드 스위즐링에서 이 값을 읽습니다.

네트워크 요청 추적

Amplitude가 네트워크 요청을 추적하도록 하려면 AutocaptureOptions.networkTracking을 autocapture구성에 포함하십시오.

let amplitude = Amplitude(configuration: Configuration(
    apiKey: "API_KEY",
    autocapture: .networkTracking
))

기본 구성에서 SDK는 상태 코드 500~599을 가진 모든 호스트(*.amplitude.com제외)의 네트워크 요청을 추적합니다. 추적 동작을 사용자 정의하려면 NetworkTrackingOptions 을(를) Configuration.networkTrackingOptions (으)로 설정하십시오.

captureRules: [
    .init(hosts: ["*"], statusCodeRange: "400-499,500-599"),
    .init(hosts: ["*.example.com", "example.com"], statusCodeRange: "0,500-599"),
]

기본 구성은 상태 코드 500~599을 가진 모든 호스트(*.amplitude.com 제외)를 추적합니다.

사용 예:

// Style 1: Use the default configuration and append a new rule
let networkTrackingOptions = NetworkTrackingOptions.default // contain a rule for all hosts, statusCodeRange: "500-599"
networkTrackingOptions.captureRules.append(
    .init(hosts: ["*.example.com", "example.com"], statusCodeRange: "0,500-599")
)
networkTrackingOptions.ignoreHosts.append("notmyapi.com")
let amplitude = Amplitude(configuration: Configuration(
    apiKey: "API_KEY",
    autocapture: .networkTracking,
    networkTrackingOptions: networkTrackingOptions,
))
// Style 2: Create a new configuration with a custom rule
let amplitude = Amplitude(configuration: Configuration(
    apiKey: "API_KEY",
    autocapture: .networkTracking,
    networkTrackingOptions: .init(
        captureRules: [
            .init(hosts: ["*"]), // all hosts, statusCodeRange: "500-599"
            .init(hosts: ["*.example.com", "example.com"], statusCodeRange: "0,400-599"),
        ],
        ignoreHosts: ["notmyapi.com"]
    ),
))

이 설정을 활성화하면 Amplitude는 애플리케이션이 네트워크 요청을 할 때마다 [Amplitude] Network Request이벤트를 추적합니다. SDK는 URL 로딩 시스템 메소드를 스위즐링하여 네트워크 활동을 계측합니다.

@_spi(NetworkTracking) import AmplitudeSwift
let amplitude = Amplitude(configuration: Configuration(
    apiKey: "API_KEY",
    autocapture: .networkTracking,
    networkTrackingOptions: .init(
        captureRules: [
            .init(hosts: ["*"]), // all hosts, statusCodeRange: "500-599"
            .init(urls: [.regex("^https://example\\.com/api/.*"), .exact("https://example.com/api2/status")],
                  methods: ["POST"],
                  statusCodeRange: "0,400-599",
                  requestHeaders: .init(allowlist: ["Link", "X-API-Key"]),
                  responseHeaders: .init(allowlist: ["Link", "X-API-Key"], captureSafeHeaders: false),
                  requestBody: .init(allowlist: ["user/*", "product/**/id"]),
                  responseBody: .init(allowlist: ["profile/**"], excludelist: ["**/password"])),
        ],
        ignoreHosts: ["notmyapi.com"],
        ignoreAmplitudeRequests: true
    ),
))

딥 링크 추적

딥 링크 추적은 자동화되어 있지 않습니다. 딥 링크를 추적하려면 해당 링크를 따라 발생하는 이벤트를 추적하십시오.

let amplitude = Amplitude(configuration: Configuration(
    apiKey: "API_KEY"
))
amplitude.track(DeepLinkOpenedEvent(url: URL()))
amplitude.track(DeepLinkOpenedEvent(url: "url", referrer:"referrer"))
amplitude.track(DeepLinkOpenedEvent(activity: activity))

Amplitude는 URL과 리퍼러 정보를 사용하여 [Amplitude] Deep Link Opened이벤트를 추적합니다.

요소 상호 작용 추적

Amplitude는 UIKit애플리케이션의 UIControl요소 및 UIGestureRecognizer 객체와의 사용자 상호 작용을 추적할 수 있습니다. 이 옵션을 활성화하려면 AutocaptureOptions.elementInteractions를 autocapture구성에 포함하십시오.

let amplitude = Amplitude(configuration: Configuration(
    apiKey: "API_KEY",
    autocapture: .elementInteractions
))

이 설정을 활성화하면 Amplitude는 사용자가 애플리케이션의 요소와 상호작용할 때마다 [Amplitude] Element Interacted이벤트를 추적합니다. SDK는 UIApplication.sendAction(_:to:from:for:)메서드와 UIGestureRecognizer.state속성 세터를 각각 액션 메서드와 애플리케이션 첫 사용 후 UIControl계측하도록 UIGestureRecognizer스위즐링합니다.

불만 유발 상호작용 추적

버전 1.15.0+에서 사용할 수 있습니다.

Amplitude는 UIKit 애플리케이션에서 UIControl 요소 및 UIGestureRecognizer 객체와의 불만 유발 상호작용(레이지 클릭 및 데드 클릭)을 추적할 수 있습니다. 이 옵션을 활성화하려면 AutocaptureOptions.frustrationInteractions를 autocapture구성에 포함하십시오.

let amplitude = Amplitude(configuration: Configuration(
    apiKey: "API_KEY",
    autocapture: .frustrationInteractions
))

interactionsOptions 구성은 레이지 클릭 및 데드 클릭을 캡처하기 위한 옵션을 구성하는 InteractionsOptions 객체를 허용합니다.

let amplitude = Amplitude(configuration: Configuration(
    apiKey: "API_KEY",
    autocapture: .frustrationInteractions,
    interactionsOptions: .init(
        rageClick: .init(enabled: true),
        deadClick: .init(enabled: true)
    )
))

레이지 클릭은 동일한 요소에 대해 1초에 4회 이상 발생하는 사용자 상호작용이며, 각 인접한 클릭 사이의 거리는 50포인트를 초과하지 않습니다.

레이지 클릭(Rage Click)이 발생하면 Amplitude는 해당 [Amplitude] Rage Click이벤트를 추적합니다.

데드 클릭은 상호작용 가능한 요소를 탭했지만 이후 3초 동안 화면에 아무런 변화가 나타나지 않는 경우를 말합니다.

데드 클릭이 발생하면 Amplitude는 [Amplitude] Dead Click 이벤트를 추적합니다.

뷰 무시

레이지 클릭 및 데드 클릭 탐지에서 특정 UIView을(를) 제외하려면 해당 뷰에서 amp_ignoreInteractionEvent(rageClick:deadClick:)을(를) 호출하세요. 두 매개변수의 기본값은 true입니다. 이 메서드는 UIKit 뷰에만 적용됩니다.

// Ignore both rage clicks and dead clicks on this view.
myView.amp_ignoreInteractionEvent()
// Or ignore only dead clicks.
myView.amp_ignoreInteractionEvent(rageClick: false, deadClick: true)

사용자 그룹

Amplitude는 사용자를 그룹에 할당하고 해당 그룹에 대해 고유 사용자별 수행 회수가와 같은 쿼리를 실행할 수 있도록 지원합니다. 적어도 한 명의 그룹 구성원이 특정 이벤트를 수행한 경우 해당 그룹도 수행 회수가에 포함됩니다.

예를 들어 'orgId'를 사용하여 사용자가 속한 조직을 기준으로 사용자를 그룹화하려는 경우가 있습니다. Joe는 'orgId' '10'에 있고 Sue는 'orgId' '15'에 있습니다. Sue와 Joe는 둘 다 특정 이벤트를 수행합니다. 이벤트 세분화 차트에서 해당 조직을 쿼리할 수 있습니다.

그룹을 설정할 때 groupType및 groupName를 정의하십시오. 이전 예시에서 'orgId'는 groupType이고 '10'과 '15'는 groupName에 대한 값입니다. groupType의 또 다른 예로는 'tennis' 및 'baseball'과 같은 groupName 값을 가진 'sport'가 있을 수 있습니다.

groupType:groupName또한 그룹을 설정하면 를 사용자 속성으로 설정하고 해당 사용자의 groupType에 대해 설정된 전체 groupName값과 해당 사용자 속성 값을 덮어씁니다. groupType은 문자열이며 사용자가 여러 그룹에 속해 있음을 나타내는 문자열 또는 문자열 groupName배열을 허용합니다.

// set group with a single group name
amplitude.setGroup(groupType: "orgId", groupName: "15")

// set group with multiple group names
amplitude.setGroup(groupType: "sport", groupName: ["tennis", "soccer"])

groups을 포함한 Event 객체를 track에 전달하여 이벤트 수준 그룹을 설정할 수도 있습니다. 이벤트 수준 그룹의 경우 그룹 지정은 사용자가 기록하는 특정 이벤트에만 적용되며 setGroup를 사용하여 명시적으로 설정하지 않는 한 사용자에게 지속되지 않습니다.

amplitude.track(
    event: BaseEvent(
        eventType: "event type",
        eventProperties: [
            "eventPropertyKey": "eventPropertyValue"
        ],
        groups: ["orgId": "15"]
    )
)

그룹 식별

Group Identify API를 사용하여 특정 그룹의 속성을 설정하거나 업데이트하십시오. 다음 고려 사항에 유의하십시오.

• 업데이트는 향후 이벤트에만 영향을 미치며 과거 이벤트를 업데이트하지는 않습니다.
• 최대 5개의 고유 그룹 유형과 총 10개의 그룹을 추적할 수 있습니다.

groupIdentify 메서드는 그룹 유형 문자열 매개변수, 그룹 이름 객체 매개변수 및 Amplitude가 그룹에 적용하는 Identify 객체를 허용합니다.

let groupType = "plan"
let groupName = "enterprise"
let identify = Identify().set(property: "key", value: "value")
amplitude.groupIdentify(groupType: groupType, groupName: groupProperty, identify: identify)

매출 추적

Amplitude는 사용자가 창출한 수익을 추적할 수 있습니다. Amplitude는 Amplitude의 이벤트 세분화 및 수익 LTV (Lifetime Value) 차트에서 사용되는 특수 필드를 갖춘 별도의 수익 객체를 통해 수익을 추적합니다. 이를 통해 Amplitude는 플랫폼의 수익과 관련된 데이터를 자동으로 표시할 수 있습니다. 수익 객체는 다음과 같은 특수 속성과 eventProperties필드를 통해 사용자 정의 속성을 지원합니다.

let revenue = Revenue()
revenue.price = 3.99
revenue.quantity = 3
revenue.productId = "com.company.productId"
amplitude.revenue(revenue: revenue)

사용자 지정 사용자 ID

앱에 사용자를 추적하려는 자체 로그인 시스템이 있는 경우 언제든지 setUserId를 호출할 수 있습니다.

amplitude.setUserId(userId: "user@amplitude.com")

현재 userId의 값을 얻으려면 헬퍼 메소드 getUserId()을 사용하십시오.

let userId = amplitude.getUserId()

사용자 지정 장치 ID

deviceId를 사용하여 새 장치 ID를 할당할 수 있습니다. 사용자 지정 장치 ID를 설정할 때는 값이 충분히 고유한지 확인하십시오. Amplitude는 UUID 사용을 권장합니다.

amplitude.setDeviceId(deviceId: NSUUID().uuidString)

맞춤형 스토리지

Amplitude가 정의한 위치 외부에 데이터를 저장하려면 스토리지 프로토콜을 구현하고 구성에서 storageProvider를 설정하여 자체 스토리지를 사용자 지정하십시오.

모든 iOS 앱은 자체적으로 저장 공간을 갖게 되므로 다른 앱과 충돌하지 않고도 앱의 파일을 여기에서 읽고 쓸 수 있습니다. 기본적으로 Amplitude는 이 파일 저장소를 사용하며 앱 '문서' 디렉토리 내에 접두사 'Amplitude' 폴더를 생성합니다. 네이티브 iOS '파일' 앱에서 Documents 폴더를 노출해야 하지만 'Amplitude' 접두사 폴더를 노출하고 싶지 않은 경우, 초기화 시 이벤트를 유지하도록 자체 스토리지 공급자를 사용자 지정할 수 있습니다.

Amplitude(
    configuration: Configuration(
        apiKey: AMPLITUDE_API_KEY,
        storageProvider: YourOwnStorage() // YourOwnStorage() should implement Storage
    )
)

사용자가 로그아웃할 때 재설정

reset는 사용자가 로그아웃한 후 익명화하는 바로 가기입니다. 방법은 다음과 같습니다.

• userId을 null로 설정합니다.
• deviceId을 현재 구성에 따라 새 값으로 설정합니다.

userId이 비어 있고 deviceId가 완전히 새로운 값인 경우, 현재 사용자는 대시보드에 완전히 새로운 사용자로 표시됩니다.

amplitude.reset()

플러그인

플러그인을 사용하면 이벤트 속성을 수정하거나(보강 유형), 타사 API로 전송(목적지 유형)하는 등의 방법으로 Amplitude SDK의 동작을 확장할 수 있습니다. 플러그인은 setup() 및 execute() 메서드를 가진 객체입니다.

플러그인 유형

SDK는 플러그인을 각 이벤트에 고정된 순서로 적용합니다. 즉, before 플러그인이 먼저 실행된 다음 enrichment 플러그인, 그 다음에 destination 플러그인이 실행됩니다. observe와(과) 같은 다른 플러그인 유형은 이 파이프라인 외부에서 실행됩니다.

• before 플러그인(PluginType.before)은 모든 보강 플러그인 앞에 실행됩니다. IT를 사용하여 다른 플러그인이 읽기 전에 이벤트 필드를 조기에 설정하거나 보호하십시오. 이것은 보강 플러그인과 동일한 형태를 가지며, type은(는) PluginType.before(으)로 설정되어 있습니다.
• enrichment 플러그인(PluginType.enrichment)은 이벤트 속성을 추가하는 등, 각 이벤트를 전달할 때 이벤트를 수정하거나 보강합니다. 보강 유형 플러그인 예제로 이동하세요.
• destination 플러그인(PluginType.destination)은 이벤트를 타사 API 등의 목적지로 전송하고 파이프라인을 종료합니다. 목적지 유형 플러그인 예제로 이동하세요.
• observe 플러그인(PluginType.observe)은 이벤트 파이프라인 외부에서 실행됩니다. 이것은 이벤트를 처리하는 대신 onUserIdChanged, onDeviceIdChanged, onSessionIdChanged 및 onOptOutChanged을(를) 재정의하여 ID 변경에 대응합니다.

다음 관찰 플러그인은 사용자가 로그인하거나 로그아웃할 때 반응합니다.

class LoginObserverPlugin: ObservePlugin {
    override func onUserIdChanged(_ userId: String?) {
        // React to login or logout.
    }
}
amplitude.add(plugin: LoginObserverPlugin())

Plugin.setup

이 메서드는 플러그인을 사용할 준비를 위한 논리를 포함하고 있으며 인스턴스를 amplitude매개변수로 사용합니다. 이 메서드의 일반적인 용도는 플러그인 종속성을 인스턴스화하는 데 사용됩니다. SDK는 amplitude.add()를 통해 클라이언트에 플러그인을 등록할 때 이 메서드를 호출합니다.

Plugin.execute

이 메서드는 이벤트를 처리하기 위한 논리를 포함하고 있으며 인스턴스를 event매개변수로 사용합니다. 강화 유형 플러그인으로 사용될 경우 예상되는 반환 값은 수정 또는 강화된 이벤트입니다. 목적지 유형 플러그인으로 사용될 경우 예상되는 반환 값은 null입니다. SDK는 Identify, GroupIdentify 및 Revenue 이벤트를 비롯하여 클라이언트 인터페이스를 사용하여 계측하는 각 이벤트에 대해 이 메서드를 호출합니다.

보강 유형 플러그인 예제

다음은 추가 이벤트 속성을 추가하여 각 계측된 이벤트를 수정하는 플러그인의 예입니다.

class EnrichmentPlugin: Plugin {
    let type: PluginType
    var amplitude: Amplitude?
    init() {
        self.type = PluginType.enrichment
    }
    func setup(amplitude: Amplitude) {
        self.amplitude = amplitude
    }
    func execute(event: BaseEvent?) -> BaseEvent? {
        event?.sessionId = -1
        if event?.eventProperties == nil {
            event?.eventProperties = [:]
        }
        event?.eventProperties?["event prop key"] = "event prop value"
        return event
    }
}
amplitude.add(plugin: EnrichmentPlugin())

목적지 유형 플러그인 예제

목적지 플러그인에서 track(), identify(), groupIdentify(), revenue() 및 flush() 함수를 덮어쓸 수 있습니다.

class TestDestinationPlugin: DestinationPlugin {
    override func track(event: BaseEvent) -> BaseEvent? {
        return event
    }
    override func identify(event: IdentifyEvent) -> IdentifyEvent? {
        return event
    }
    override func groupIdentify(event: GroupIdentifyEvent) -> GroupIdentifyEvent? {
        return event
    }
    override func revenue(event: RevenueEvent) -> RevenueEvent? {
        return event
    }
    override func flush() {
    }
    override func setup(amplitude: Amplitude) {
        self.amplitude = amplitude
    }
    override func execute(event: BaseEvent?) -> BaseEvent? {
        return event
    }
}

플러그인 제거

플러그인이 이벤트를 처리하지 못하도록 막으려면, 동일한 플러그인 인스턴스를 remove(plugin:)에 전달하세요.

let plugin = EnrichmentPlugin()
amplitude.add(plugin: plugin)
// Later, remove it.
amplitude.remove(plugin: plugin)

문제 해결 및 디버깅

구성과 페이로드가 정확한지 확인하고 디버깅 다음 기간동안 전체 비정상적인 메시지가 있는지 확인하십시오. 모든 것이 정상적인 것으로 보이면 flushQueueSize 또는 flushIntervalMillis의 값을 확인하십시오. SDK는 기본적으로 이벤트를 대기열에 넣고 일괄 처리로 전송하므로 해당 이벤트를 즉시 서버로 전달하지는 않습니다. SDK가 서버에 이벤트를 전송할 때까지 기다린 후 차트에서 해당 이벤트를 확인하십시오.

로그

• 디버깅 중에 유용한 정보를 수집하려면 로그 수준을 디버그로 설정하십시오.
• LoggerProvider 에서 loggerProvider 클래스를 사용자 정의하고 운영 환경의 서버에 오류 메시지를 기록하는 것과 같은 고유한 논리를 구현하십시오.

플러그인

목적지 플러그인을 사용하여 구성 값과 이벤트 페이로드를 서버로 전송하기 전에 인쇄하십시오. l로그 수준을 디버그로 설정하고 다음 TroubleShootingPlugin을 프로젝트에 복사한 다음 Amplitude 인스턴스에 플러그인을 추가하십시오.

SwiftUI TroubleShootingPlugin 예제입니다.

이벤트 콜백

이벤트 콜백은 SDK가 성공 및 실패 이벤트 모두에 대해 이벤트를 전송한 후 실행됩니다. 이 방법을 사용하여 이벤트 상태와 메시지를 모니터링할 수 있습니다. 자세한 내용은 구성 > 콜백을 참조하십시오.

고급옵션 항목

사용자 세션

Amplitude는 앱이 포그라운드로 이동하거나 SDK가 백그라운드에서 이벤트를 추적할 때 세션을 시작합니다. 앱이 setMinTimeBetweenSessionsMillis()에서 설정한 시간보다 백그라운드에 머물면서 어떤 이벤트도 추적하지 않으면 세션이 종료됩니다. 또는 configuration.defaultTracking가 세션 추적을 활성화하는지 여부와 관계없이 앱이 포그라운드에 있는 전체 시간 동안 세션은 계속됩니다.configuration.autocapture

앱이 포그라운드에 진입하면 Amplitude는 세션 시작을 추적하고 setMinTimeBetweenSessionsMillis()에 따라 카운트다운을 시작합니다. Amplitude는 세션을 연장하고 IT가 새 이벤트를 추적하는 전체 시간마다 카운트다운을 다시 시작합니다. 카운트다운이 만료되면 Amplitude는 다음 이벤트가 있을 때까지 기다리며 세션 종료 이벤트를 추적합니다.

Amplitude는 기본적으로 세션 이벤트에 대한 사용자 속성을 설정하지 않습니다. 이러한 속성을 추가하려면 identify() 및 setUserId()를 사용하십시오. Amplitude는 사용자 속성 상태를 집계하고 device_id 또는 user_id에 따라 사용자를 이벤트와 연결합니다.

Amplitude가 세션을 관리하는 방식 때문에 SDK가 예상대로 작동하더라도 몇 가지 시나리오에서 이벤트가 누락된 것처럼 보이거나 세션 추적이 부정확하게 발생할 수 있습니다.

• 사용자가 앱으로 돌아오지 않는 경우, Amplitude는 세션 시작 이벤트와 일치하도록 세션 종료 이벤트를 추적하지 않습니다.
• 백그라운드에서 이벤트를 추적하는 경우 Amplitude는 사용자가 포그라운드에서 앱을 사용한 시간보다 세션 길이를 더 길게 인식할 수 있습니다.
• 마지막 이벤트와 세션 종료 이벤트 대상 구간 사용자 속성을 수정하는 경우 세션 종료 이벤트는 업데이트된 사용자 속성을 반영하며, 이 속성은 동일한 세션의 이벤트와 연관된 다른 속성과 다를 수 있습니다. 이 문제를 해결하려면 보강 플러그인을 사용해 세션 종료 이벤트에서 event['$skip_user_properties_sync']을 true로 설정하십시오. 이렇게 하면 Amplitude가 해당 특정 이벤트에 대한 속성을 동기화하지 못하게 됩니다. 자세한 내용은 변환기 구성 참조 문서의 $skip_user_properties_sync를 참조하십시오.

Amplitude는 이벤트를 세션별로 그룹화합니다. 동일한 세션 내에서 기록된 이벤트는 동일한 session_id를 공유합니다. Amplitude는 세션을 자동으로 처리하므로 수동으로 startSession() 또는 endSession()을 호출할 필요가 없습니다.

다음 기간동안 Amplitude가 세션을 연장하는 시간 윈도우를 조정할 수 있습니다. 기본 세션 만료 시간은 5분입니다.

현재 sessionId의 값을 얻으려면 헬퍼 메소드 getSessionId을 사용하십시오.

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

또한 이벤트를 세션 외에도 추적할 수 있습니다. 세션 외 이벤트는 -1의 sessionId 값을 갖고 있으며 다음과 같이 동작합니다.

1. 현재 세션의 일부가 아닙니다.
2. 현재 세션을 연장하지 않습니다.
3. 새 세션을 시작하지 않습니다.
4. 후속 이벤트의 sessionId를 변경하지 않습니다.

잠재적 사용 사례는 푸시 알림에서 추적되는 이벤트이며, 이는 일반적으로 고객의 앱 사용 외부에서 발생합니다.

EventOptions에서 sessionId를 -1로 설정하면 track(event, options) 또는 identify(identify, options)을 호출할 때 이벤트가 세션 외 이벤트로 표시됩니다.

let outOfSessionOptions = EventOptions(sessionId: -1)
amplitude.identify(
    event: Identify().set(property: "user-prop", value: true),
    options: outOfSessionOptions
)
amplitude.track(
    event: BaseEvent(eventType: "Button Clicked"),
    options: outOfSessionOptions
)

세션 ID를 수동으로 설정하려면, 밀리초 단위의 Unix 타임스탬프나 Date을(를) 사용하여 setSessionId을(를) 호출하세요. 음수가 아닌 타임스탬프는 해당 시점에 새 세션을 시작하고 음수의 타임스탬프는 현재 세션을 종료합니다.

// Start a new session at the current time.
amplitude.setSessionId(timestamp: Int64(Date().timeIntervalSince1970 * 1000))
// Or pass a Date directly.
amplitude.setSessionId(date: Date())

로그 수준

개발자 콘솔에 출력되는 로그 수준을 제어합니다.

• 'OFF': 모든 로그 메시지를 숨깁니다.
• 'ERROR': 오류 메시지만 표시합니다.
• 'WARN': 오류 메시지와 경고를 표시합니다. 이 수준은 문제가 될 수 있고 데이터에 이상한 점을 일으킬 수 있는 문제를 기록합니다. 예를 들어 이 수준은 Null 값을 가진 속성에 대한 경고를 표시합니다.
• 'LOG': 이벤트에 대한 정보성 메시지를 표시합니다.
• 'DEBUG': 디버깅에 유용할 수 있는 오류 메시지, 경고 및 유용한 메시지를 표시합니다.

로그 수준 logLevel을 원하는 수준으로 설정하십시오.

let amplitude = Amplitude(
    configuration: Configuration(
        apiKey: AMPLITUDE_API_KEY,
        logLevel: LogLevelEnum.log
    )
)

Amplitude는 사용자 데이터를 병합하므로, Amplitude는 알려진 userId 또는 deviceId에 관련된 모든 이벤트를 기존 사용자와 연결합니다.

사용자가 로그아웃하면 Amplitude는 해당 사용자의 로그아웃 이벤트를 해당 사용자의 기록과 병합할 수 있습니다. 이 동작을 변경하고 해당 이벤트를 익명 사용자에게 기록할 수 있습니다.

익명 사용자에게 이벤트를 기록하려면 다음을 수행하십시오.

1. userId를 null로 설정합니다.
2. 새 deviceId를 생성합니다.

현재 사용자 또는 기기의 이벤트는 Amplitude에서 새 사용자로 나타납니다. 참고: 이 작업을 수행하면 두 사용자가 동일한 장치를 사용하고 있었음을 알 수 없습니다.

amplitude.reset()

추적 비활성화

기본적으로 iOS SDK는 carrier, city, country, ip_address, language 및 platform과 같은 여러 사용자 속성을 추적합니다. 제공된 TrackingOptions 인터페이스를 사용하여 개별 필드를 사용자 정의하고 토글할 수 있습니다. apiKey를 사용하여 SDK를 초기화하기 전에 사용자의 구성으로 TrackingOptions 인스턴스를 생성하고, 이를 SDK 인스턴스에 설정하십시오.

let trackingOptions = TrackingOptions()
trackingOptions.disableTrackCity().disableTrackIpAddress()
let amplitude = Amplitude(
    configuration: Configuration(
        apiKey: AMPLITUDE_API_KEY,
        trackingOptions: trackingOptions
    )
)

각 필드에 대한 추적을 개별적으로 제어할 수 있으며, 각 필드에는 해당 메서드가 있습니다(예: disableCountry, disableLanguage).

이동통신사

Amplitude는 CTTelephonyNetworkInfo를 사용하여 사용자의 이동통신사를 결정하며, 이는 sim의 등록된 통신사업자를 반환합니다.

COPPA 제어

IDFA, IDFV, 도시, IP 주소 및 위치 추적에 대한 COPPA(아동 온라인 개인정보 보호법) 제한을 한 번에 활성화 또는 비활성화할 수 있습니다. 13세 미만의 어린이로부터 정보를 요청하는 앱은 COPPA를 준수해야 합니다.

let amplitude = Amplitude(
    configuration: Configuration(
        apiKey: AMPLITUDE_API_KEY,
        enableCoppaControl: true
    )
)

광고주 ID

광고주 ID(IDFA라고도 함)는 iOS 및 Google Play 스토어에서 제공하는 고유 식별자입니다. 이는 사용자의 기기뿐만 아니라 모든 사람에게 고유하기 때문에 모바일 어트리뷰션에 유용합니다.

모바일 어트리뷰션은 모바일 앱의 설치가 원래 Target(예: 광고 캠페인, 앱 스토어 검색)에 기인하는 것을 말합니다. 모바일 앱은 IDFA를 요청하기 위해 권한이 필요하며, 어린이를 대상으로 한 앱은 전혀 추적할 수 없습니다. IDFA를 사용할 수 없는 경우 IDFV, 장치 ID 또는 이메일 로그인 시스템을 사용하는 것을 고려하십시오.

IDFA를 검색하여 이벤트 추적에 추가하려면 이 예시 플러그인을 참조하여 자체 플러그인을 구현하십시오.

장치 ID 생애주기 분석

SDK는 다음 순서로 장치 ID를 초기화하고 장치 ID를 발견한 첫 번째 유효한 값으로 설정합니다.

1. Amplitude 인스턴스의 장치 ID(setDeviceId()을 통해 설정한 경우).
2. IDFV(존재하는 경우)입니다.
3. 무작위로 생성된 UUID 문자열입니다.

한 명의 사용자가 여러 장치를 사용

단일 사용자는 각각 다른 장치 ID를 가진 여러 장치를 가질 수 있습니다. 일관성을 유지하려면 이러한 모든 장치에서 사용자 ID를 일관되게 설정하십시오. 장치 ID가 다르더라도 Amplitude는 여전히 이들을 하나의 Amplitude ID로 병합하여 고유 사용자로 식별할 수 있습니다.

새 장치로 전송

사용자가 새 장치로 전환할 때 여러 장치가 동일한 장치 ID를 가질 수 있습니다. 사용자가 새로운 장치로 전환할 때 사용자는 종종 다른 관련 데이터와 함께 자신의 애플리케이션을 전송합니다. 전송되는 특정 콘텐츠는 애플리케이션에 따라 다를 수 있습니다. 일반적으로 IT에는 앱과 관련된 데이터베이스 및 파일 디렉토리가 포함됩니다. 그러나 포함되는 정확한 항목은 앱의 디자인과 개발자가 선택한 사항에 따라 다릅니다. 사용자가 한 장치에서 다른 장치로 데이터베이스 또는 파일 디렉터리를 백업한 경우, 그 안에 저장된 장치 ID가 여전히 남아 있을 수 있습니다. 결과적으로 SDK가 초기화 다음 기간동안 IT를 검색하면 다른 장치가 동일한 장치 ID를 사용하게 될 수 있습니다.

장치 ID 가져오기

현재 deviceId의 값을 얻으려면 헬퍼 메소드 getDeviceId()을 사용하십시오.

let deviceId = amplitude.getDeviceId()

장치를 설정하려면 사용자 지정 장치 ID를 참조하십시오.

위치 추적

Amplitude는 기본적으로 사용자 이벤트의 IP를 위치(GeoIP 조회)로 변환합니다. 앱의 자체 추적 솔루션 또는 사용자 데이터는 이 정보를 무시할 수 있습니다.

사용자를 추적에서 해제합니다

사용자는 추적을 완전히 거부하기를 원할 수 있습니다. 이는 Amplitude가 자신의 이벤트나 브라우징 기록을 전체 추적하지 않음을 의미합니다. OptOut은 사용자의 개인정보 보호 요청을 충족할 수 있는 방법을 제공합니다.

let amplitude = Amplitude(
    configuration: Configuration(
        apiKey: AMPLITUDE_API_KEY,
        optOut: true
    )
)

로그 콜백 설정

LoggerProvider에서 사용자 지정 클래스를 구현하고 초기화 다음 기간동안 IT를 구성에 전달하여 프로덕션 환경에서 SDK로부터 오류 메시지를 수집하는 데 도움loggerProvider을 줍니다.

class SampleLogger: Logger {
    typealias LogLevel = LogLevelEnum
    var logLevel: Int
    init(logLevel: Int = LogLevelEnum.off.rawValue) {
        self.logLevel = logLevel
    }
    func error(message: String) {
        // TODO: handle error message
    }
    func warn(message: String) {
        // TODO: handle warn message
    }
    func log(message: String) {
        // TODO: handle log message
    }
    func debug(message: String) {
        // TODO: handle debug message
    }
}
let amplitude = Amplitude(
    configuration: Configuration(
        apiKey: AMPLITUDE_API_KEY,
        loggerProvider: SampleLogger()
    )
)

보안

iOS는 각 앱의 데이터를 자체 보안 디렉토리에 저장하여 애플리케이션 데이터를 자동으로 보호합니다. 다른 응용 프로그램은 일반적으로 이 디렉토리에 액세스할 수 없습니다. 그러나 기기가 탈옥된 경우 앱은 기기의 모든 디렉토리에 대한 루트 액세스 권한을 갖습니다.

탈옥한 장치에서 다른 앱이 앱의 Amplitude 데이터에 액세스하지 못하도록 하기 위해 Amplitude는 SDK에 고유한 인스턴스 이름을 설정할 것을 권장합니다. 이렇게 하면 다른 앱과 격리된 고유한 데이터베이스가 생성됩니다.

let amplitude = Amplitude(
    configuration: Configuration(
        apiKey: "API-KEY",
        instanceName: "my-unique-instance-name"
    )
)

오프라인 모드

버전 1.3.0부터 Amplitude iOS Swift SDK는 오프라인 모드를 지원합니다. SDK는 이벤트를 추적할 때마다 네트워크 연결을 확인합니다. 디바이스가 네트워크에 연결되어 있는 경우 SDK는 플러시를 예약합니다. 그렇지 않은 경우 SDK는 이벤트를 스토리지에 저장합니다. 또한 SDK는 네트워크 연결의 변경 사항을 수신하고 장치가 다시 연결될 때 저장된 모든 이벤트를 플러시합니다.

오프라인 모드를 비활성화하려면 초기화에 offline: NetworkConnectivityCheckerPlugin.Disabled을(를) 추가하세요.

let amplitude = Amplitude(
    configuration: Configuration(
        apiKey: "API-KEY",
        offline: NetworkConnectivityCheckerPlugin.Disabled
    )
)

또한 자신만의 오프라인 로직을 구현할 수도 있습니다.

1. 위와 같이 기본 오프라인 로직을 비활성화합니다.
2. amplitude.configuration.offline을 직접 토글하십시오.

Apple 개인정보 보호 매니페스트

2020년 12월 8일부터 Apple은 모든 새로운 앱과 앱 업데이트에 대해 개인정보 보호 매니페스트 파일을 요구합니다. Apple은 2024년 봄에 이를 의무화할 예정입니다. Amplitude는 앱에 대한 제3자이므로, Amplitude를 사용자 데이터와 함께 사용하는 방식을 사용자에게 적절하게 공개해야 합니다.

NSPrivacyTracking

기본적으로 Amplitude는 추적을 위해 데이터를 사용하지 않습니다. 이 필드를 추가하고 앱에서 IT를 지원하는 경우 이를 true로 설정하세요.

NSPrivacyCollectedDataTypes

기본적으로 SDK는 deviceId만 추적합니다. setUserId()를 사용하여 userId도 추적할 수 있습니다. 이렇게 하려면 "사용자 ID" 데이터 유형을 추가하십시오. 데이터 유형에 대한 자세한 내용은 Apple의 기사 '개인정보 보호 매니페스트의 데이터 사용 설명'을 참조하십시오.

NSPrivacyTrackingDomains

NSPrivacyTracking을 참으로 설정한 경우, 구성에 따라 NSPrivacyTrackingDomains에 인터넷 도메인을 하나 이상 제공하십시오.

NSPrivacyAccessedAPITypes

SDK는 ID 저장용으로만 userDefaultsAPI를 사용합니다.

앱의 개인정보 보호 리포트 작성

앱 개인정보 보호 설정 방법에 설명된 단계를 따르십시오.