안드로이드-코틀린 SDK
Android Kotlin SDK(com.amplitude:analytics-android)는 Android 앱을 계측하고 이벤트를 Amplitude로 전송합니다. 새로운 Android 앱과 세션, 자동 캡처 및 플러그인 파이프라인이 필요한 Kotlin 또는 Java 클라이언트에 사용하십시오. 여전히 유지 관리 Android SDK(com.amplitude:android-sdk)에 의존하는 경우 이 SDK로 마이그레이션하십시오.
통합 SDK
분석을 세션 리플레이 및 실험과 함께 사용하려면 Android용 통합 SDK를 설치하십시오.
시스템 요구 사항
Android Kotlin SDK는 Android API 레벨 21(Android 5.0 Lollipop) 이상을 지원합니다.
SDK 설치
Amplitude는 Android Studio를 IDE로 사용하고 Gradle을 사용하여 종속성을 관리할 것을 권장합니다.
프로젝트에서 Gradle을 사용하는 경우, build.gradle에 다음 종속성을 추가하고 업데이트된 파일과 프로젝트를 동기화하십시오.
dependencies {
implementation 'com.amplitude:analytics-android:1.+'
}
SDK 초기화
이벤트를 추적하기 전에 SDK를 초기화하십시오. Amplitude 프로젝트 API 키와 Android 애플리케이션 컨텍스트가 필요합니다. 프로세스당 한 번씩 초기화하고 해당 인스턴스를 재사용합니다.
import com.amplitude.android.Amplitude
val amplitude = Amplitude(AMPLITUDE_API_KEY, applicationContext) {
// Set configuration options here.
}
초기화 위치
Amplitude는 Application.onCreate에서 초기화할 것을 권장합니다. 그래야 SDK가 모든 액티비티가 시작되기 전에 준비되고 자동 캡처가 전체 앱 생애주기 분석에 등록됩니다.
import android.app.Application
import com.amplitude.android.Amplitude
class MyApplication : Application() {
override fun onCreate() {
super.onCreate()
amplitude = Amplitude(AMPLITUDE_API_KEY, applicationContext) {
// Set configuration options here.
}
}
companion object {
lateinit var amplitude: Amplitude
}
}
Activity 컨텍스트가 아닌 애플리케이션 컨텍스트를 전달합니다. SDK에는 앱 생애주기 분석을 관찰하기 위해 애플리케이션이 필요합니다.
의존성 주입
Hilt, Koin 또는 Dagger와 같은 DI 프레임워크를 사용하는 경우, Amplitude를 애플리케이션 컨텍스트로 구축된 애플리케이션 범위의 싱글톤으로 제공하고, 이벤트를 추적하는 모든 위치에 해당 인스턴스를 삽입하십시오.
다음 사항에 유의하십시오.
- 프로세스당 하나의 인스턴스를 생성합니다.
instanceName를 공유하는 인스턴스는 스토리지와 ID를 공유합니다. - 먼저 인스턴스를 구성한 다음, 호출하고
setUserId추적합니다.
사용 가능한 구성 옵션은 SDK 구성을 참조하십시오.
SDK 구성
일괄 처리 동작 구성
고성능 환경을 지원하기 위해 SDK는 이벤트를 일괄 처리로 전송합니다. SDK는 메서드가 기록하는 모든 이벤트를 메모리에 대기열에 넣고 백그라운드에서 track배치로 플러시합니다.flushQueueSize 및 flushIntervalMillis을 사용하여 일괄 처리 동작을 사용자 지정할 수 있습니다. serverUrl가 null이거나 비어 있으면 useBatch = true가 배치 엔드포인트를 선택합니다. 값이 비어 있지 않으면 영역 및 배치 엔드포인트 선택을 재정의합니다serverUrl. 일반 모드와 배치 모드 모두 동일한 이벤트 업로드 임계값과 플러시 시간 간격을 사용합니다.
업로드가 실패하면 SDK는 지수적 백오프 스케줄에 따라 재시도합니다. 재시도는 무제한입니다. 사용 중단된 flushMaxRetries옵션은 아무 효과가 없습니다.
import com.amplitude.android.Amplitude
val amplitude = Amplitude(AMPLITUDE_API_KEY, applicationContext) {
flushIntervalMillis = 50000
flushQueueSize = 20
}
EU 데이터 상주
Amplitude의 EU 서버로 데이터를 전송하도록 클라이언트를 초기화할 때 서버 영역을 구성하십시오. SDK는 사용자가 서버 영역을 설정한 경우 이를 기반으로 데이터를 전송합니다.
EU 데이터 상주를 위해서는 Amplitude EU 내에서 프로젝트를 설정하십시오. Amplitude EU의 API 키를 사용하여 SDK를 초기화하십시오.
import com.amplitude.android.Amplitude
val amplitude = Amplitude(AMPLITUDE_API_KEY, applicationContext) {
serverZone = ServerZone.EU
}
사용자 지정 HTTP 클라이언트
SDK는 기본적으로 네트워크 요청에 HttpURLConnection을 사용합니다. 사용자 지정 HTTP 클라이언트를 사용하려면 HttpClientInterface를 구현하여 httpClient 구성 옵션에 전달하십시오.
OkHttp - gzip 압축
샘플 앱은 이벤트 업로드를 위해 gzip 압축을 사용하는 사용자 지정 OkHttp 클라이언트를 만드는 방법을 보여줍니다.
- GzipRequestInterceptor - 요청 본문을 압축하는 OkHttp 인터셉터입니다.
- CustomOkHttpClient - OkHttp를 사용한
HttpClientInterface구현.
사용자 지정 클라이언트를 사용하려면 다음과 같이 하십시오.
val httpClient = CustomOkHttpClient()
val amplitude = Amplitude(AMPLITUDE_API_KEY, applicationContext) {
this.httpClient = httpClient
}
httpClient.initialize(amplitude.configuration)
SDK의 기본 HTTP 클라이언트는 이미 gzip을 사용하여 요청 본문을 압축합니다. 사용자 지정 시간 초과, 인증서 고정 또는 로깅 인터셉터와 같은 추가 기능이 필요한 경우 사용자 지정 OkHttp 클라이언트를 사용하십시오.
추적
이벤트는 사용자가 애플리케이션과 상호 작용하는 방식을 나타냅니다. 예를 들어 "재생된 노래"는 메모해야 할 동작일 수 있습니다.
amplitude.track("Song Played")
설정 및 수집 확인
첫 이벤트 수집 확인
기본적으로 Android Kotlin SDK는 이벤트를 대기열에 추가하고 30초마다 또는 30개의 이벤트가 쌓인 후, 먼저 발생하는 경우에 업로드합니다. 이벤트를 즉시 확인하려면 이후track()에 amplitude.flush()를 호출하십시오.
Logger.LogMode.DEBUG를 사용하는 로거로 loggerProvider를 구성합니다. debug, info, warn 및 error 메서드를 태그 Amplitude와(과) 함께 Android의 Log 메서드로 전송합니다. 예를 들어 provider 및 디버그 메서드는 다음 패턴을 사용합니다.
import android.util.Log
import com.amplitude.common.Logger
import com.amplitude.core.LoggerProvider
class DebugLogger : Logger {
override var logMode: Logger.LogMode
get() = Logger.LogMode.DEBUG
set(value) {}
override fun debug(message: String) {
Log.d("Amplitude", message)
}
override fun info(message: String) {
Log.i("Amplitude", message)
}
override fun warn(message: String) {
Log.w("Amplitude", message)
}
override fun error(message: String) {
Log.e("Amplitude", message)
}
}
class DebugLoggerProvider : LoggerProvider {
override fun getLogger(amplitude: com.amplitude.core.Amplitude): Logger = DebugLogger()
}
val amplitude = Amplitude(AMPLITUDE_API_KEY, applicationContext) {
loggerProvider = DebugLoggerProvider()
}
Android Studio에서 Logcat을 열고 tag:Amplitude로 필터링합니다. SDK가 이벤트를 오류 없이 대기열에 넣고 업로드하는지 확인하십시오.
사용자 조회 활동을 열고 이벤트의 사용자 또는 장치 ID를 찾은 다음 라이브 이벤트 업데이트를 활성화합니다. 이벤트가 활동 스트림에 나타나는지 확인합니다.
또한 이벤트 속성을 선택적으로 포함할 수도 있습니다.
amplitude.track(
"Song Played",
mutableMapOf<String, Any?>("title" to "Happy Birthday")
)
보다 복잡한 이벤트의 경우 객체 BaseEvent를 만들고 추적할 수 있습니다.
var event = BaseEvent()
event.eventType = "Song Played"
event.eventProperties = mutableMapOf<String, Any?>("title" to "Happy Birthday")
event.groups = mutableMapOf<String, Any?>("test-group-type" to "test-group-value")
event.insertId = "1234"
amplitude.track(event)
Identify
릴리스 v1.7.0부터 SDK는 set 작업만 포함된 identify 이벤트를 일괄 처리합니다. 이러한 일괄 처리는 전송되는 이벤트의 수를 줄여주며, set 작업의 실행 방식에는 영향을 주지 않습니다. identifyBatchIntervalMillis구성 설정을 사용하여 SDK가 일괄 처리 식별 인터셉트를 플러시하는 간격을 관리할 수 있습니다.
Identify 는 전체 이벤트를 전송하지 않고 특정 사용자의 사용자 속성을 설정합니다. SDK는 개별 사용자 속성에 대해 set, setOnce, unset, add, append, prepend, preInsert, postInsert, remove 및 clearAll 작업을 지원합니다. Identify 인터페이스를 사용하여 작업을 선언합니다. 하나의 Identify 객체에 여러 작업을 연결한 다음 Identify 객체를 Amplitude 클라이언트에 전달하여 서버로 전송할 수 있습니다.
이벤트 후에 Identify 호출을 전송하면 작업 결과가 대시보드 사용자의 프로필 영역에 즉시 나타나지만 SDK가 Identify 호출 후에 다른 이벤트를 전송할 때까지 차트 결과에 나타나지 않습니다. ID 호출은 앞으로 진행되는 이벤트에만 영향을 줍니다.
identify 메서드를 사용하여 사용자의 ID를 처리하십시오. 이러한 방법을 적절하게 사용하면 이벤트가 장치, 브라우저 및 기타 플랫폼 간에 이동할 때 올바른 사용자에게 연결됩니다. 이러한 사용자 속성 작업이 포함된 identify 호출을 Amplitude 서버로 전송하여 사용자의 이벤트를 특정 사용자 속성과 연결합니다.
val identify = Identify()
identify.set("color", "green")
amplitude.identify(identify)
식별 작업
Identify 객체는 다음 작업을 지원합니다.
| 작업 | 설명 |
|---|---|
set | 사용자 속성의 값을 설정합니다. 기존 값을 덮어씁니다. |
setOnce | 사용자 속성의 값을 한 번만 설정합니다. 후속 호출은 초기 값을 덮어쓰지 않습니다. |
add | 숫자 사용자 속성에 숫자 값을 추가합니다. |
append | 사용자 속성 배열에 값을 추가합니다. |
prepend | 사용자 속성 배열 앞에 값을 추가합니다. |
preInsert | 사용자 속성 배열에 값이 아직 존재하지 않는 경우 해당 값을 해당 배열의 시작 부분에 추가합니다. |
postInsert | 사용자 속성 배열에 값이 아직 존재하지 경우 값을 배열의 끝에 추가합니다. |
remove | 사용자 속성 배열에서 값을 제거합니다. |
unset | 사용자 속성을 제거합니다. |
clearAll | 모든 사용자 속성을 지웁니다. |
val identify = Identify()
identify
.set("color", "green")
.setOnce("initial_source", "organic")
.add("login_count", 1)
.append("visited_pages", "home")
.prepend("notifications", "new_feature")
.preInsert("tags", "beta")
.postInsert("tags", "vip")
.remove("visited_pages", "home")
.unset("temporary_property")
amplitude.identify(identify)
모든 사용자 속성 지우기
clearAll()을 사용하여 현재 사용자의 모든 사용자 속성을 지웁니다. 이 작업은 되돌릴 수 없습니다.
주의해서 사용하십시오.
clearAll() 작업은 모든 사용자 속성을 제거합니다. 이 작업은 영구적입니다. 이 명령은 취소할 수 없습니다.
val identify = Identify()
identify.clearAll()
amplitude.identify(identify)
자동 캡처
v1.18.0 릴리스부터 SDK는 수동 계측 없이 더 많은 이벤트를 추적할 수 있습니다. 다음 이벤트를 자동으로 추적하도록 SDK를 구성하십시오.
- 세션.
- 앱 수명 주기.
- 화면 보기.
- 딥 링크.
- 요소 상호 작용.
- 불만스러운 상호 작용:
- 레이지 클릭.
- 데드 클릭.
Amplitude를 구성하여 오토캡처 이벤트 추적을 시작합니다. 그렇지 않으면 구성을 생략하여 세션 추적만 활성화된 상태로 유지하십시오.
The autocapture 구성은 Set의 AutocaptureOption값을 허용합니다. 자동 캡처 옵션을 생성하려면 autocaptureOptions 헬퍼 함수를 사용하고 각 옵션 앞에 단항 더하기 기호(+)를 붙여 옵션을 세트에 추가하십시오.
import com.amplitude.android.Amplitude
val amplitude = Amplitude(AMPLITUDE_API_KEY, applicationContext) {
autocapture = autocaptureOptions {
+sessions // or `+AutocaptureOption.SESSIONS`
+appLifecycles // or `+AutocaptureOption.APP_LIFECYCLES`
+deepLinks // or `+AutocaptureOption.DEEP_LINKS`
+screenViews // or `+AutocaptureOption.SCREEN_VIEWS`
+elementInteractions // or `+AutocaptureOption.ELEMENT_INTERACTIONS`
+frustrationInteractions // or `+AutocaptureOption.FRUSTRATION_INTERACTIONS`
}
}
기본적으로 초기화 중에 autocapture 구성을 명시적으로 설정하지 않으면 configuration.autocapture는 자동으로 AutocaptureOption.SESSIONS를 포함합니다.
자동 세션 이벤트 캡처를 방지하려면 AutocaptureOption.SESSIONS 옵션 없이 autocapture을 설정하십시오.
import com.amplitude.android.Amplitude
val amplitude = Amplitude(AMPLITUDE_API_KEY, applicationContext) {
autocapture = setOf(AutocaptureOption.APP_LIFECYCLES) // or use `setOf()` to disable autocapture.
}
세션 추적
Amplitude는 기본적으로 세션 추적을 활성화합니다. AutocaptureOption.SESSIONS을 autocapture 구성에 포함하여 SDK가 세션 이벤트를 추적하도록 명시적으로 구성하거나, 다른 자동 캡처 구성과 함께 세션 이벤트 트래킹을 활성화할 수 있습니다.
import com.amplitude.android.Amplitude
val amplitude = Amplitude(AMPLITUDE_API_KEY, applicationContext) {
autocapture = autocaptureOptions {
+sessions // or `+AutocaptureOption.SESSIONS`
}
}
세션 추적에 대한 자세한 내용은 사용자 세션을 참조하십시오.
애플리케이션 수명주기 추적
autocapture 구성에 AutocaptureOption.APP_LIFECYCLES을 포함시켜 애플리케이션 생애주기 분석 이벤트 트래킹을 활성화하십시오. 다음 코드 샘플을 참조하십시오.
import com.amplitude.android.Amplitude
val amplitude = Amplitude(AMPLITUDE_API_KEY, applicationContext) {
autocapture = autocaptureOptions {
+appLifecycles // or `+AutocaptureOption.APP_LIFECYCLES`
}
}
이 설정을 활성화하면 Amplitude는 다음 이벤트를 추적합니다.
[Amplitude] Application Installed: 설치 직후 사용자가 애플리케이션을 처음 열 때 발생합니다. 속성:[Amplitude] Version,[Amplitude] Build.[Amplitude] Application Updated: 사용자가 애플리케이션을 업데이트한 후 애플리케이션을 열 때 발생합니다. 속성:[Amplitude] Previous Version,[Amplitude] Previous Build,[Amplitude] Version,[Amplitude] Build.[Amplitude] Application Opened: 사용자가 처음 연 후 애플리케이션을 실행하거나 포그라운드로 전환할 때 발생합니다. 속성:[Amplitude] From Background,[Amplitude] Version,[Amplitude] Build.[Amplitude] Application Backgrounded: 사용자가 애플리케이션을 백그라운드로 전환할 때 발생합니다. 이 이벤트에는 속성이 없습니다.
화면 뷰 추적
autocapture 구성에 AutocaptureOption.SCREEN_VIEWS을 포함시켜 화면 및 프래그먼트 보기 이벤트 트래킹을 활성화하십시오. 다음 코드 샘플을 참조하십시오.
import com.amplitude.android.Amplitude
val amplitude = Amplitude(AMPLITUDE_API_KEY, applicationContext) {
autocapture = autocaptureOptions {
+screenViews // or `+AutocaptureOption.SCREEN_VIEWS`
}
}
이 설정을 활성화하면 Amplitude는 [Amplitude] Screen Viewed및 [Amplitude] Fragment Viewed 이벤트를 모두 추적합니다. 두 이벤트 모두 화면 이름 속성을 포함합니다. [Amplitude] Fragment Viewed이벤트의 경우 Amplitude는 추가 프래그먼트 관련 속성을 캡처합니다.
딥 링크 추적
autocapture 구성에 AutocaptureOption.DEEP_LINKS을 포함시켜 딥링크 이벤트 트래킹을 활성화하십시오. 다음 코드 샘플을 참조하십시오.
import com.amplitude.android.Amplitude
val amplitude = Amplitude(AMPLITUDE_API_KEY, applicationContext) {
autocapture = autocaptureOptions {
+deepLinks // or `+AutocaptureOption.DEEP_LINKS`
}
}
이 설정을 활성화하면 Amplitude는 URL 및 리퍼러 정보를 사용하여 [Amplitude] Deep Link Opened이벤트를 추적합니다.
단일 작업 활동에서 딥 링크 처리
활동이 singleTop, singleTask, 또는 singleInstance 시작 모드를 사용하는 경우, Android는 새 활동을 생성하는 대신 해당 활동이 이미 실행되고 있는 동안 도착하는 딥 링크를 onNewIntent()로 전달합니다. 이 경우, Amplitude가 딥링크를 추적할 수 있도록 setIntent()를 호출하여 활동의 인텐트를 업데이트하십시오.
override fun onNewIntent(intent: Intent) {
super.onNewIntent(intent)
setIntent(intent) // Required for Amplitude to track the deep link
}
setIntent()을(를) 호출하지 않으면 getIntent()은(는) 활동을 시작한 원래 인텐트를 계속 반환하며, Amplitude는 새로운 딥링크를 감지하지 못합니다.
요소 상호 작용 추적
Amplitude는 클래식 Android Views와 Jetpack Compose를 모두 지원하며 클릭 가능한 요소를 사용한 사용자 상호 작용을 추적할 수 있습니다. 이 옵션을 활성화하려면 AutocaptureOption.ELEMENT_INTERACTIONS를 autocapture구성에 포함하십시오.
import com.amplitude.android.Amplitude
val amplitude = Amplitude(AMPLITUDE_API_KEY, applicationContext) {
autocapture = autocaptureOptions {
+elementInteractions // or `+AutocaptureOption.ELEMENT_INTERACTIONS`
}
}
이 설정을 활성화하면 Amplitude는 사용자가 애플리케이션의 요소와 상호작용할 때마다 [Amplitude] Element Interacted이벤트를 추적합니다.
Jetpack Compose는 [Amplitude] Target Class, [Amplitude] Target Resource, [Amplitude] Target Text및 [Amplitude] Hierarchy를 생략합니다.
Jetpack Compose 지원
Amplitude는 Jetpack Compose에 구현된 모든 클릭 가능한 UI 요소와의 사용자 상호 작용을 추적합니다. Modifier.testTag은(는) 선택 사항입니다. [Amplitude] Target Tag속성에 추가 식별을 제공하기 위해 이를 @Composable함수에 추가하십시오. 설정하지 않은 경우testTag에도, Amplitude는 설정값이 적용된 상태로 [Amplitude] Target Source상호 작용을 계속 추적합니다Jetpack Compose.
더 나은 요소 식별을 위해 testTag 사용
testTag는 선택 사항이지만 Amplitude는 사용자가 클릭한 특정 Compose 뷰를 식별할 것을 권장합니다. testTag속성은 다음과 같은 몇 가지 이점을 제공합니다.
- 정확한 요소 식별: 분석 데이터에서 유사한 UI 요소(예: 여러 버튼이나 카드)를 구별하는 데 도움을 줍니다.
- 안정적인 추적: UI 구조나 스타일을 업데이트하거나 수정해도 변경되지 않는 일관된 식별자를 제공합니다.
- 분석 용이성: Amplitude 차트의 특정 요소와의 상호 작용을 간편하게 필터링하고 분석할 수 있습니다.
- 플랫폼 간 일관성: 서로 다른 플랫폼에서 일관된 요소 이름을 유지합니다.
// Example: Adding testTag for better identification
Button(
onClick = { /* handle click */ },
modifier = Modifier.testTag("login_button")
) {
Text("Log In")
}
Card(
onClick = { /* handle click */ },
modifier = Modifier.testTag("product_card_${product.id}")
) {
// Card content
}
사용자가 이러한 요소를 클릭하면 [Amplitude] Target Tag 속성에 testTag 값이 포함되므로 사용자가 분석 데이터에서 어떤 특정 요소와 상호작용했는지 쉽게 식별할 수 있습니다.
불만 유발 상호작용 추적
Amplitude는 Android Views와 Jetpack Compose에서 클릭 가능한 UI 요소를 사용하여 좌절감을 주는 상호작용(분노 클릭과 죽은 클릭)을 추적할 수 있습니다. 이 옵션을 활성화하려면 AutocaptureOption.FRUSTRATION_INTERACTIONS를 autocapture구성에 포함하십시오.
import com.amplitude.android.Amplitude
val amplitude = Amplitude(AMPLITUDE_API_KEY, applicationContext) {
autocapture = autocaptureOptions {
+frustrationInteractions // or `+AutocaptureOption.FRUSTRATION_INTERACTIONS`
}
}
레이지 클릭은 사용자가 1초 이내에 동일한 요소를 4회 이상 클릭하고, 각 클릭 간격이 50픽셀(장치 독립) 이내인 경우 발생합니다. SDK는 전체 클릭 버스트를 보고하며[Amplitude] Click Count, [Amplitude] Clicks보고된 횟수에는 상한이 없습니다.
레이지 클릭(Rage Click)이 발생하면 Amplitude는 해당 [Amplitude] Rage Click이벤트를 추적합니다.
데드 클릭은 사용자가 상호작용 가능 요소에 대해 상호 작용했지만, 이후 3초 동안 화면에 아무런 변화가 없는 경우입니다.
데드 클릭이 발생하면 Amplitude는 [Amplitude] Dead Click 이벤트를 추적합니다.
불만족 상호 작용 유형 구성
FRUSTRATION_INTERACTIONS을 활성화하면 레이지 클릭과 데드 클릭을 모두 추적합니다. interactionsOptions 매개변수를 사용하여 각 유형을 개별적으로 활성화 또는 비활성화할 수 있습니다.
import com.amplitude.android.Amplitude
import com.amplitude.android.InteractionsOptions
import com.amplitude.android.RageClickOptions
import com.amplitude.android.DeadClickOptions
val amplitude = Amplitude(AMPLITUDE_API_KEY, applicationContext) {
autocapture = autocaptureOptions {
+frustrationInteractions
}
interactionsOptions = InteractionsOptions(
rageClick = RageClickOptions(enabled = true),
deadClick = DeadClickOptions(enabled = false)
)
}
비활성 클릭에는 세션 리플레이가 필요합니다.
비활성 클릭을 추적하려면 세션 리플레이 및 불만족 상호 작용을 모두 활성화하십시오.
불만족 분석에서 특정 요소를 무시하십시오.
일부 UI 요소는 예상되는 빠른 클릭을 생성하거나 의미있는 불만감 신호를 제공하지 않습니다. 무시 API를 사용하여 이러한 요소를 불만 분석에서 제외하면서도 일반적인 상호작용 이벤트는 계속 추적할 수 있습니다.
일반적인 활용 사례:
- 탐색 요소: 뒤로 버튼, 닫기 버튼 및 서랍 토글.
- 멀티클릭 요소: 증분/감소 버튼과 좋아요/즐겨찾기 버튼.
- 로딩 표시기: 진행률 표시줄, 스피너 및 로딩 버튼.
- 장식 요소: 비기능적 UI 구성 요소입니다.
Android 보기
Android 보기에 대한 좌절 분석을 무시하는 데 FrustrationAnalyticsUtils사용하십시오.
import com.amplitude.android.FrustrationAnalyticsUtils
// Ignore all frustration analytics for this view
val backButton = findViewById<Button>(R.id.back_button)
FrustrationAnalyticsUtils.ignoreFrustrationAnalytics(backButton)
// Ignore only rage clicks (allow dead click detection)
val incrementButton = findViewById<Button>(R.id.increment_button)
FrustrationAnalyticsUtils.ignoreFrustrationAnalytics(
incrementButton,
rageClick = true,
deadClick = false
)
// Remove ignore marker from a view
FrustrationAnalyticsUtils.unignoreView(backButton)
Jetpack Compose
Modifier.ignoreFrustrationAnalytics()확장 기능을 사용하여 컴포즈 요소에 대한 좌절 분석을 무시하십시오.
import com.amplitude.android.ignoreFrustrationAnalytics
// Ignore all frustration analytics
Button(
onClick = { finish() },
modifier = Modifier.ignoreFrustrationAnalytics()
) { Text("Back") }
// Ignore only dead clicks (allow rage click detection)
Button(
onClick = { submitForm() },
modifier = Modifier.ignoreFrustrationAnalytics(
rageClick = false,
deadClick = true
)
) { Text("Submit") }
매개변수 조합
rageClick | deadClick | 행동 방식 |
|---|---|---|
true (기본값) | true (기본값) | 모든 좌절 분석을 무시하십시오 |
true | false | 레이지 클릭 감지만 무시하십시오 |
false | true | 데드 클릭 감지만 무시하십시오 |
false | false | 둘 다 추적(아무것도 무시하지 않음) |
불만 분석을 무시하고 ELEMENT_INTERACTIONS를 활성화할 경우, SDK는 여전히 일반 요소 상호 작용 이벤트([Amplitude] Element Interacted)를 추적합니다. Ignore는 해당 이벤트를 발생시키지 않습니다. 해당 이벤트를 억제하지 않을 뿐입니다. 이 설정은 레이지 클릭 및 데드 클릭 이벤트에만 영향을 줍니다.
사용자 그룹
Amplitude는 사용자를 그룹에 할당하고 해당 그룹에 대해 고유 사용자별 수행 회수가와 같은 쿼리를 실행할 수 있도록 지원합니다. 그룹 구성원 중 하나 이상이 특정 이벤트를 수행하는 경우 해당 그룹도 수행 회수가에 포함됩니다.
예를 들어, orgId를 사용하여 사용자를 조직별로 그룹화하려는 경우를 생각해 보겠습니다. Joe는 orgId 10에 속하고, Sue는 orgId 15에 속합니다. 수와 조 둘 다 특정 이벤트를 수행합니다. 이벤트 세분화 차트에서 해당 조직을 쿼리할 수 있습니다.
그룹을 설정할 때 groupType 및 groupName를 정의하십시오. 이전 예시에서 orgId는 groupType이고 10와 15은 groupName의 값입니다. groupType의 또 다른 예로는 sport이 있으며, groupName 값은 tennis 및 baseball와 같이 구성됩니다.
또한 그룹을 설정하면 groupType:groupName이 사용자 속성으로 설정되며, 해당 사용자의 groupType에 대한 모든 기존 groupName 값과 해당 사용자 속성 값을 덮어씁니다. groupType은 문자열이며, groupName은 사용자가 여러 그룹에 속해 있음을 나타내는 문자열 또는 문자열 배열입니다.
Joe가 orgId 15에 속해 있다면, groupName은(는) 15입니다.
// set group with a single group name
amplitude.setGroup("orgId", "15")
Joe가 sport tennis 및 soccer에 속해 있다면, groupName는 ["tennis", "soccer"]입니다.
// set group with multiple group names
amplitude.setGroup("sport", arrayOf("tennis", "soccer"))
또한 BaseEvent 객체에 groups를 전달하여 track에 이벤트 수준 그룹을 설정할 수도 있습니다. 이벤트 수준 그룹의 경우, 그룹 지정은 사용자가 기록하는 특정 이벤트에만 적용되며 setGroup를 사용하여 명시적으로 설정하지 않는 한 해당 지정이 사용자에게 계속 적용되지는 않습니다.
val event = BaseEvent()
event.eventType = "event type"
event.eventProperties = mutableMapOf("event property" to "event property value")
event.groups = mutableMapOf("orgId" to "15")
amplitude.track(event)
그룹 식별
Group Identify API를 사용하여 특정 그룹의 속성을 설정하거나 업데이트하십시오. 다음 고려 사항에 유의하십시오.
- 업데이트는 향후 이벤트에만 영향을 미치며 과거 이벤트를 업데이트하지는 않습니다.
- 최대 5개의 고유 그룹 유형과 총 10개의 그룹을 추적할 수 있습니다.
groupIdentify이 메서드는 Amplitude가 그룹에 적용하는 그룹 유형 문자열 매개변수, 그룹 이름 String매개변수 및 식별 객체를 허용합니다.
val groupType = "plan"
val groupName = "enterprise"
val identify = Identify().set("key", "value")
amplitude.groupIdentify(groupType, groupName, identify)
매출 추적
Amplitude는 사용자가 창출한 수익을 추적할 수 있습니다. Amplitude는 Amplitude의 이벤트 세분화 및 수익 LTV (Lifetime Value) 차트에서 사용하는 특수 필드를 갖춘 별개의 수익 객체를 통해 수익을 추적합니다. 수익 객체는 플랫폼의 수익과 관련된 데이터를 자동으로 표시합니다. 수익 객체는 다음과 같은 특수 속성과 properties필드를 통해 사용자 정의 속성을 지원합니다.
val revenue = Revenue()
revenue.productId = "com.company.productId"
revenue.price = 3.99
revenue.quantity = 3
amplitude.revenue(revenue)
| 이름 | 설명 |
|---|---|
productId | 선택 사항입니다. 문자열입니다. 제품의 식별자입니다. Amplitude는 Google Play 스토어 제품 ID와 같은 것을 권장합니다. 기본값은 null입니다. |
quantity | 선택 사항입니다. 정수입니다. 구매한 제품의 수량입니다. 기본값은 1.revenue = quantity * price입니다. |
price | 필수입니다. Double. 구입한 제품의 가격입니다. 음수일 수 있습니다. 기본값은 무엇이며null, isValid()이 필요합니다price. |
revenue | 선택 사항입니다. Double. 수익 금액입니다. 기본값은 null입니다. |
currency | 선택 사항입니다. 문자열입니다. 3자리 통화 코드입니다. 기본값은 null입니다. |
revenueType | 선택 사항이지만, 수익 검증을 위해 필요합니다. 문자열입니다. 수익 유형(예: 세금, 환급금, 소득)입니다. 기본값은 null입니다. |
receipt | 선택 사항입니다. 문자열입니다. 수익의 영수증 식별자입니다. 예를 들어, 123456. 기본값은 null입니다. |
receiptSig | 선택 사항이지만, 수익 검증을 위해 필요합니다. 문자열입니다. 기본값은 null입니다. setReceipt(receipt, receiptSignature)를 호출할 수도 있습니다. |
properties | 선택 사항입니다. 추가 이벤트 속성의 맵입니다. 기본값은 null입니다. |
사용자 정의 사용자 식별자
앱에 자체 로그인 시스템이 있고 이를 이용하여 사용자를 추적하려는 경우, 언제든지 setUserId을 호출하십시오.
amplitude.setUserId("user@amplitude.com")
현재 사용자 ID를 가져오려면 getUserId()을(를) 호출하십시오.
val userId = amplitude.getUserId()
사용자 지정 장치 식별자
deviceId를 사용하여 새 장치 ID를 할당하십시오. 사용자 지정 장치 ID를 설정할 때는 값이 충분히 고유한지 확인하십시오. Amplitude는 UUID 사용을 권장합니다.
import java.util.UUID
amplitude.setDeviceId(UUID.randomUUID().toString())
사용자가 로그아웃할 때 재설정
reset는 사용자가 로그아웃한 후 익명화하는 바로 가기입니다. 방법은 다음과 같습니다.
userId을null로 설정합니다.deviceId을 현재 구성에 따라 새 값으로 설정합니다.
userId이 비어 있고 deviceId가 완전히 새로운 값인 경우, 현재 사용자는 대시보드에 완전히 새로운 사용자로 표시됩니다.
amplitude.reset()
SDK 플러그인
플러그인을 사용하면 이벤트 속성을 수정하거나(보강 유형), 타사 API로 전송(목적지 유형)하는 등의 방법으로 Amplitude SDK의 동작을 확장할 수 있습니다. 플러그인은 setup() 및 execute() 메서드를 가진 객체입니다.
플러그인 유형
SDK는 각 이벤트에 고정된 순서로 플러그인을 적용합니다. 즉, BeforeBefore 플러그인이 먼저 실행되고, 그다음으로 Enrichment 플러그인, Destination 플러그인 순으로 실행됩니다.Utility 및 Observe 플러그인은 이 파이프라인 외부에서 실행됩니다.
Before플러그인(Plugin.Type.Before)은 모든 보강 플러그인 앞에 실행됩니다. 이를 사용하면 다른 플러그인들이 이벤트 필드를 읽기 전에 일찍 설정하거나 보호할 수 있습니다. 이것은 보강 플러그인과 동일한 형태를 가지며,type은(는)Plugin.Type.Before(으)로 설정되어 있습니다.Enrichment플러그인(Plugin.Type.Enrichment)은 이벤트 속성을 추가하는 등, 각 이벤트를 전달할 때 이벤트를 수정하거나 보강합니다. 보강 유형 플러그인 예제로 이동하십시오.Destination플러그인(Plugin.Type.Destination)은 이벤트를 타사 API 등의 목적지로 전송하고 파이프라인을 종료합니다. 목적지 유형 플러그인 예제로 이동하십시오.Utility플러그인(Plugin.Type.Utility)은 이전 → 강화 → 목적지 파이프라인 외부에서 실행됩니다.NetworkTrackingPlugin와 같이 이벤트를 변환하지 않는 SDK 수준 통합에 사용하십시오.Observe플러그인(Plugin.Type.Observe)은 이벤트 파이프라인 외부에서 실행됩니다. 이벤트를 처리하는 대신,onUserIdChanged,onDeviceIdChanged,onSessionIdChanged,onOptOutChanged,onIdentityChanged및onReset콜백을 통해 ID 및 세션 변경에 대응합니다. 클래스를 확장하고 필요한ObservePlugin콜백을 재정의합니다.onUserIdChanged및onDeviceIdChanged를 재정의해야 합니다.
다음 관찰 플러그인은 사용자가 로그인하거나 로그아웃할 때 반응합니다.
import com.amplitude.core.Amplitude
import com.amplitude.core.platform.ObservePlugin
class LoginObserverPlugin : ObservePlugin() {
override lateinit var amplitude: Amplitude
override fun onUserIdChanged(userId: String?) {
// React to login or logout.
}
override fun onDeviceIdChanged(deviceId: String?) {}
}
amplitude.add(LoginObserverPlugin())
Plugin.setup
이 메서드는 플러그인을 준비하고 amplitude 인스턴스를 매개변수로 받습니다. Kotlin에서는 Unit을, Java에서는 void을 반환합니다. 이 메서드의 일반적인 용도는 플러그인 종속성을 인스턴스화하는 데 사용됩니다. 플러그인을 amplitude.add()로 등록할 때 SDK는 이 메서드를 호출합니다.
Plugin.execute
이 메서드는 이벤트를 처리하기 위한 로직을 포함하고 있으며 인스턴스를 event매개변수로 사용합니다. 강화 및 이전 플러그인은 execute를 재정의하고 수정된 이벤트를 반환하거나, null를 반환하여 삭제합니다. 목적지 플러그인에 대해 execute재정의하지 마십시오. DestinationPlugin.execute 는 final이고 null를 반환합니다. flush대신 , identify, groupIdentify, 및 revenue를 track재정의합니다.
보강 유형 플러그인 예제
다음 플러그인은 추가 이벤트 속성을 추가하여 각 계측된 이벤트를 수정합니다.
import com.amplitude.core.Amplitude
import com.amplitude.core.events.BaseEvent
import com.amplitude.core.platform.Plugin
class EnrichmentPlugin : Plugin {
override lateinit var amplitude: Amplitude
override val type = Plugin.Type.Enrichment
override fun execute(event: BaseEvent): BaseEvent {
val properties = event.eventProperties ?: mutableMapOf()
properties["custom android event property"] = "test"
event.eventProperties = properties
return event
}
}
amplitude.add(EnrichmentPlugin())
목적지 유형 플러그인 예제
목적지 플러그인에서 track(), identify(), groupIdentify(), revenue(), 및 flush()를 재정의합니다. DestinationPlugin.execute는 final이고 null를 반환합니다.
import com.amplitude.core.Amplitude
import com.amplitude.core.events.BaseEvent
import com.amplitude.core.platform.DestinationPlugin
import com.segment.analytics.Analytics
import com.segment.analytics.Properties
class SegmentDestinationPlugin(
private val context: android.content.Context,
private val writeKey: String,
) : DestinationPlugin() {
private lateinit var analytics: Analytics
override fun setup(amplitude: Amplitude) {
super.setup(amplitude)
analytics = Analytics.Builder(context, writeKey).build()
Analytics.setSingletonInstance(analytics)
}
override fun track(event: BaseEvent): BaseEvent {
val properties = Properties()
event.eventProperties?.forEach { (key, value) ->
properties.putValue(key, value)
}
analytics.track(event.eventType, properties)
return event
}
}
amplitude.add(SegmentDestinationPlugin(this, SEGMENT_WRITE_KEY))
플러그인 제거
플러그인이 이벤트를 처리하지 못하도록 막으려면, 동일한 플러그인 인스턴스를 remove()에 전달하십시오.
val plugin = EnrichmentPlugin()
amplitude.add(plugin)
// Later, remove it.
amplitude.remove(plugin)
네트워크 추적 플러그인
네트워크 추적 플러그인은 URL, 상태 코드, 타이밍 정보를 포함하여 OkHttp를 통해 이루어진 네트워크 요청과 응답을 캡처합니다. 네트워크 추적은 자동 캡처의 일부가 아니며 수동 연동이 필요합니다. 추적하려는 각 OkHttp 클라이언트에 플러그인을 인터셉터로 추가한 다음, Amplitude 인스턴스에 추가하십시오. 이 플러그인은 사용자가 계측하는 OkHttp 클라이언트를 통해 전달되는 요청만 캡처합니다.
설치
네트워크 추적 플러그인은 OkHttp 종속성을 필요로 합니다. 프로젝트에 추가하려면 다음과 같이 하십시오.
dependencies {
// OkHttp is required for the NetworkTrackingPlugin
implementation 'com.squareup.okhttp3:okhttp:4.12.0'
}
구성
기본 구성을 사용하고 OkHttp와 통합하기 위해 플러그인을 인터셉터로 추가하십시오:
import com.amplitude.android.network.NetworkTrackingPlugin
// Create the plugin with default configuration
val networkPlugin = NetworkTrackingPlugin()
// Add the plugin as an interceptor to your OkHttp client
val okHttpClient = OkHttpClient.Builder()
.addInterceptor(networkPlugin)
.build()
// Add the plugin to your Amplitude instance
amplitude.add(networkPlugin)
기본 구성은 상태 코드 500~599인 *.amplitude.com을 제외한 모든 호스트를 추적합니다.
추적 동작을 사용자 정의하고 추적할 요청을 제어하려면 NetworkTrackingOptions설정하십시오. v1.31.0부터 NetworkTrackingOptions 생성자는 @JvmOverloads를 지원하므로 Java 호출자는 기본값을 가진 후행 매개 변수를 생략할 수 있습니다.
import com.amplitude.android.Amplitude
import com.amplitude.android.network.NetworkTrackingOptions
import com.amplitude.android.network.NetworkTrackingPlugin
import com.amplitude.android.network.NetworkTrackingOptions.CaptureRule
// Create custom capture rules
val options = NetworkTrackingOptions(
captureRules = listOf(
// Track all responses from your API domain with status code from 400 to 599
CaptureRule(
hosts = listOf("*.example.com", "example.com"),
statusCodeRange = (400..599).toList()
)
),
// Ignore specific domains
ignoreHosts = listOf("analytics.example.com", "*.internal.com"),
// Whether to ignore Amplitude API requests
ignoreAmplitudeRequests = true
)
// Create the plugin with options
val networkPlugin = NetworkTrackingPlugin(options)
// Add the plugin to your Amplitude instance
amplitude.add(networkPlugin)
및 를 ignoreHosts함께 captureRules설정할 수 있습니다. SDK는 무시된 호스트를 먼저 필터링하고, ignoreAmplitudeRequests이 true일 때 Amplitude 요청을 건너뜁니다. 나머지 호스트는 여전히 아래에서 위로 captureRules일치합니다. 예를 들어 이 구성을 사용하면 다음과 같습니다.
captureRules = listOf(
CaptureRule(
hosts = listOf("*"),
statusCodeRange = (400..599).toList()
),
CaptureRule(
hosts = listOf("*.example.com", "example.com"),
statusCodeRange = (500..599).toList()
)
)
SDK는 요청을 다음과 같이 처리합니다.
- 상태 코드 503을 가진
example.com에 대한 요청: 마지막 규칙의 호스트와 일치함 → statusCodeRange와 일치함 → 캡처됨 - 상태 코드 401을 가진
example.com에 대한 요청: 마지막 규칙의 호스트와 일치 → statusCodeRange와 일치하지 않음 → 무시됨 - 상태 코드가 401인
other.com에 대한 요청: 마지막 규칙의 호스트와 일치하지 않음 → 첫 번째 규칙의 호스트와 일치함 → statusCodeRange와 일치함 → 캡처됨 - 상태 코드가 200인
other.com에 대한 요청: 마지막 규칙의 호스트와 일치하지 않음 → 첫 번째 규칙의 호스트와 일치함 → statusCodeRange와 일치하지 않음 → 무시됨
URL, 헤더 및 요청 본문 캡처
호스트 대신 URL을 기준으로 요청을 일치시키거나 요청 및 응답 헤더와 본문을 캡처하려면 URL 기반 CaptureRule 생성자를 사용하십시오. URL을 URLPattern.Exact또는 URLPattern.Regex과 매칭시키고, HTTP 메소드로 필터링하고, CaptureHeader및 CaptureBody를 사용하여 헤더 및 본문 캡처를 선택하십시오.
import com.amplitude.android.network.NetworkTrackingOptions
import com.amplitude.android.network.NetworkTrackingOptions.CaptureRule
import com.amplitude.android.network.NetworkTrackingOptions.CaptureHeader
import com.amplitude.android.network.NetworkTrackingOptions.CaptureBody
import com.amplitude.android.network.NetworkTrackingOptions.URLPattern
val options = NetworkTrackingOptions(
captureRules = listOf(
CaptureRule(
urls = listOf(
URLPattern.Exact("https://api.example.com/v1/login"),
URLPattern.Regex("^https://api\\.example\\.com/v1/.*")
),
methods = listOf("POST"),
statusCodeRange = (200..599).toList(),
requestHeaders = CaptureHeader(allowlist = listOf("X-Request-Id")),
responseHeaders = CaptureHeader(allowlist = listOf("X-Response-Id")),
requestBody = CaptureBody(allowlist = listOf("user/*"), excludelist = listOf("**/password")),
responseBody = CaptureBody(allowlist = listOf("profile/**"))
)
)
)
amplitude.add(NetworkTrackingPlugin(options))
추적되는 이벤트 속성
플러그인이 네트워크 요청을 추적할 때 다음과 같은 속성을 가진 유형의 이벤트를 전송합니다[Amplitude] Network Request.
| 속성 | 설명 |
|---|---|
[Amplitude] URL | 민감한 정보가 마스크된 네트워크 요청의 URL입니다. |
[Amplitude] URL Query | URL의 쿼리 매개 변수입니다. |
[Amplitude] URL Fragment | URL의 프래그먼트 식별자입니다. |
[Amplitude] Request Method | 요청에 사용된 HTTP 메소드입니다(GET, POST 등). |
[Amplitude] Status Code | 응답의 HTTP 상태 코드입니다. |
[Amplitude] Error Message | 요청이 상태 코드 없이 실패한 경우 나타나는 로컬 오류 메시지입니다. |
[Amplitude] Start Time | 요청이 시작된 시점의 타임스탬프(Unix 에포크 날짜 이후 밀리초 단위)입니다. |
[Amplitude] Completion Time | 요청이 완료된 시점의 타임스탬프(Unix 에포크 날짜 이후 밀리초 단위)입니다. |
[Amplitude] Duration | 요청의 지속 시간(밀리초)입니다. |
[Amplitude] Request Body Size | 요청 본문의 크기(바이트)입니다. |
[Amplitude] Response Body Size | 응답 본문의 크기(바이트)입니다. |
[Amplitude] Request Headers | 캡처 규칙이 옵트인 시 표시되는 요청 헤더입니다. |
[Amplitude] Response Headers | 캡처 규칙이 옵트인 시 표시되는 응답 헤더입니다. |
[Amplitude] Request Body | 캡처 규칙이 옵트인 시 표시되는 요청 본문 필드입니다. |
[Amplitude] Response Body | 캡처 규칙이 옵트인 시 표시되는 응답 본문 필드입니다. |
개인정보 보호 고려 사항
네트워크 추적 플러그인은 기본적으로 다음과 같은 민감한 정보를 마스킹합니다.
- URL에 있는 인증 자격 증명(사용자 이름:암호@domain.com).
- 일반적인 민감한 쿼리 매개 변수(예: 사용자 이름, 암호, 이메일, 전화 번호)입니다.
디버깅
구성과 페이로드가 정확한지 확인하고, 디버깅 중에 비정상적인 메시지가 있는지 확인하십시오. 모든 것이 문제없어 보이면 flushQueueSize 또는 flushIntervalMillis의 값을 확인하십시오. 기본적으로 SDK는 이벤트를 대기열에 넣고 일괄적으로 전송하므로, 개별 이벤트가 즉시 서버로 전송되지는 않습니다. flush()를 호출하여 대기열에 있는 이벤트를 즉시 전송하거나, 차트에서 확인하기 전에 SDK가 이벤트를 서버로 전송할 때까지 기다립니다.
amplitude.flush()
enableDiagnostics이 기본값true인 경우, SDK는 SDK를 개선하는 데 도움이 되도록 Amplitude에 진단 정보를 전송합니다. v1.34.0부터 이 기능에는 완료되지 않은 업로드 요청에 대한 데이터가 포함되므로 중단되거나 삭제된 요청을 더 쉽게 식별할 수 있습니다. v1.36.0부터 SDK는 ANR(Application Not Responding) 이벤트와 처리되지 않은 예외를 진단으로 캡처합니다.
로그
- 디버깅 중에 유용한 정보를 수집하려면 로그 수준을 디버그로 설정하십시오.
LoggerProvider에서loggerProvider클래스를 사용자 정의하고 프로덕션 환경의 서버에 오류 메시지를 기록하는 것과 같은 고유한 논리를 구현하십시오.
플러그인
목적지 플러그인을 사용하여 구성 값과 이벤트 페이로드를 서버로 전송하기 전에 출력하십시오. logLevel을 디버그로 설정하고 다음 TroubleShootingPlugin를 프로젝트에 복사한 다음 Amplitude 인스턴스에 플러그인을 추가하십시오.
이벤트 콜백
이벤트 콜백은 SDK가 성공 및 실패 이벤트 모두에 대해 이벤트를 전송한 후 실행됩니다. 이 방법을 사용하여 이벤트 상태와 메시지를 모니터링할 수 있습니다. 이벤트별 콜백을 track(event, options, callback)에 전달하거나 EventOptions.callback로 설정합니다. configuration-table callback 설정은 별도의 인스턴스 수준의 후크입니다.
val event = BaseEvent()
event.eventType = "Button Clicked"
amplitude.track(event, EventOptions()) { e, status, message ->
// Handle success or failure.
}
고급옵션 항목
사용자 세션
Amplitude는 앱이 포그라운드로 이동하거나 SDK가 백그라운드에서 이벤트를 추적할 때 세션을 시작합니다. 앱이 minTimeBetweenSessionsMillis 옵션 이상 백그라운드에 머물면서 어떤 이벤트도 추적하지 않으면 세션이 종료됩니다. configuration.trackingSessionEvents, configuration.defaultTracking 또는 configuration.autocapture을 통해 세션 추적을 활성화했는지 여부와 관계없이 앱이 포그라운드에 있는 동안 세션은 계속됩니다.
v1.34.0의 Foreground 추적+
v1.34.0부터 SDK는 Android 포그라운드 감지를 위해 활동 생애주기 분석 대신 프로세스 생애주기 분석을 사용합니다. 이 기능은 멀티 활동 앱과 모든 액티비티가 열리기 전에 백그라운드 서비스를 시작하는 앱에서 포그라운드 감지를 수정합니다.
앱이 포그라운드에 진입하면 Amplitude는 세션 시작을 추적하고 minTimeBetweenSessionsMillis에 따라 카운트다운을 시작합니다. Amplitude는 세션을 연장하고 새 이벤트를 추적하는 전체 시간마다 카운트다운을 다시 시작합니다. 카운트다운이 만료되면 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는 앱 생애주기 분석을 통해 세션을 자동으로 처리합니다.
세션 연장을 위한 시간 범위를 조정하십시오. 기본 세션 만료 시간은 30분입니다.
val amplitude = Amplitude(AMPLITUDE_API_KEY, applicationContext) {
minTimeBetweenSessionsMillis = 10000
}
기본적으로 Amplitude는 session_start및 session_end 이벤트(Amplitude.START_SESSION_EVENT / Amplitude.END_SESSION_EVENT)를 자동으로 전송합니다. SDK가 이러한 이벤트를 전송하지 않더라도 Amplitude는 session_id를 사용하여 세션을 계속 추적합니다. 이러한 세션 이벤트를 비활성화할 수도 있습니다.
val amplitude = Amplitude(AMPLITUDE_API_KEY, applicationContext) {
autocapture = setOf()
}
현재 세션 ID를 가져오려면 sessionId 속성을 읽으십시오. Java에서는 합성된 getSessionId() 액세서를 사용하십시오.
val sessionId = amplitude.sessionId
또한 이벤트를 세션 외에도 추적할 수 있습니다. 세션 외 이벤트는 -1의 sessionId 값을 갖고 있으며 다음과 같이 동작합니다.
- 현재 세션의 일부가 아닙니다.
- 현재 세션을 연장하지 않습니다.
- 새로운 세션을 시작하지 않습니다.
- 이들은 후속 이벤트에 대해
sessionId를 변경하지 않습니다.
잠재적 사용 사례는 푸시 알림에서 추적되는 이벤트이며, 이는 일반적으로 고객의 앱 사용 외부에서 발생합니다.
EventOptions에서 sessionId를 -1로 설정하면 track(event, options) 또는 identify(identify, options)을 호출할 때 이벤트가 세션 외 이벤트로 표시됩니다.
val outOfSessionOptions = EventOptions().apply {
sessionId = -1
}
amplitude.identify(
Identify().set("user-prop", true),
outOfSessionOptions
)
amplitude.track(
BaseEvent().apply { eventType = "test event" },
outOfSessionOptions
)
로그 수준
개발자 콘솔에 출력되는 로그 수준을 제어합니다.
INFO: 이벤트에 대한 유용한 정보성 메시지를 표시합니다.WARN: 오류 메시지와 경고를 표시합니다. 이 수준은 데이터에 문제나 특이 사항을 일으킬 수 있는 문제를 기록합니다. 예를 들어 이 수준은 Null 값을 가진 속성에 대한 경고를 표시합니다.ERROR: 오류 메시지만 표시합니다.DISABLE: 모든 로그 메시지를 숨깁니다.DEBUG: 디버깅에 유용할 수 있는 오류 메시지, 경고 및 유용한 정보를 표시합니다.
원하는 수준을 지정하여 setLogLevel을 호출하여 로그 수준을 설정하십시오.
amplitude.logger.logMode = Logger.LogMode.DEBUG
로그아웃된 사용자 및 익명 사용자
Amplitude는 사용자 데이터를 병합하므로, Amplitude는 알려진 userId 또는 deviceId에 관련된 모든 이벤트를 기존 사용자와 연결합니다. 사용자가 로그아웃하면 Amplitude는 해당 사용자의 로그아웃 이벤트를 해당 사용자의 기록에 병합할 수 있습니다. 이 동작을 변경하고 해당 이벤트를 익명 사용자에게 기록할 수 있습니다.
익명 사용자에게 이벤트를 기록하려면 다음을 수행하십시오.
userId를 null로 설정합니다.- 새
deviceId를 생성합니다.
현재 사용자 또는 기기에서 발생한 이벤트는 Amplitude에서 새 사용자로 표시됩니다. 참고: 이 작업을 수행하면 두 사용자가 동일한 장치를 사용했는지 알 수 없습니다.
amplitude.reset()
추적 비활성화
기본적으로 Android SDK는 carrier, city, country, ip_address, language 및 platform과 같은 여러 사용자 속성을 추적합니다. 제공된 TrackingOptions 인터페이스를 사용하여 개별 필드를 사용자 정의하고 토글할 수 있습니다.
TrackingOptions 인터페이스를 사용하려면 클래스를 가져오십시오.
import com.amplitude.android.TrackingOptions
apiKey를 사용하여 SDK를 초기화하기 전에 사용자의 구성으로 TrackingOptions 인스턴스를 생성하고, 이를 SDK 인스턴스에 설정하십시오.
val trackingOptions = TrackingOptions()
trackingOptions.disableCity().disableIpAddress().disableLatLng()
val amplitude = Amplitude(AMPLITUDE_API_KEY, applicationContext) {
this.trackingOptions = trackingOptions
}
각 필드에 대한 추적을 개별적으로 제어할 수 있습니다. 각 필드에는 해당하는 메서드가 있습니다(예: disableCountry, disableLanguage).
| 메서드 | 설명 |
|---|---|
disableAdid() | Google ADID 추적 비활성화 |
disableAppSetId() | 앱 세트 ID 추적 비활성화 |
disableCarrier() | 기기의 통신사 추적 비활성화 |
disableCity() | 사용자의 도시 추적 비활성화 |
disableCountry() | 사용자의 국가 추적 비활성화 |
disableDeviceBrand() | 기기 브랜드 추적 비활성화 |
disableDeviceModel() | 장치 모델 추적 비활성화 |
disableDeviceManufacturer() | 장치 제조업체 추적 비활성화 |
disableDma() | 사용자의 지정된 시장 영역(DMA)에 대한 추적을 비활성화합니다. |
disableIpAddress() | 사용자의 IP 주소 추적 비활성화 |
disableLanguage() | 장치의 언어 추적 비활성화 |
disableLatLng() | 사용자의 현재 위도 및 경도 좌표 추적 비활성화 |
disableOsName() | 기기의 OS 이름 추적 비활성화 |
disableOsVersion() | 기기의 OS 버전 추적 비활성화 |
disablePlatform() | 기기 플랫폼 추적 비활성화 |
disableRegion() | 사용자의 지역 추적을 비활성화합니다. |
disableVersionName() | 앱 버전 이름 추적 비활성화 |
disableApiLevel() | Android API 수준 추적 비활성화 |
TrackingOptions을(를) 사용하는 것만으로는 데이터를 아직 전송하지 않은 새로 생성된 프로젝트에서 SDK가 기본 속성을 추적하지 못합니다. 기존 데이터가 포함된 프로젝트가 있고 기본 속성 수집을 중단하려면 Amplitude 커뮤니티에서 도움말을 얻으십시오. 추적을 비활성화해도 프로젝트의 기존 데이터는 삭제되지 않습니다.
이동통신사
Amplitude는 Android의 TelephonyManager networkOperatorName를 사용하여 사용자의 이동 통신사를 파악하며, 이 방법은 tower의 현재 등록된 운영자를 반환합니다.
COPPA 제어
COPPA(Children’s Online Privacy Protection Act) 제어를 활성화하여 Android Advertising ID, 도시, IP 주소 및 위치 좌표를 함께 비활성화할 수 있습니다. COPPA 제어는 앱 세트 ID를 비활성화하지 않습니다. 13세 미만의 어린이로부터 정보를 요청하는 앱은 COPPA를 준수해야 합니다.
val amplitude = Amplitude(AMPLITUDE_API_KEY, applicationContext) {
enableCoppaControl = true // Disables ADID, city, IP, and location tracking
}
광고주 ID
Android 광고 ID는 Google Play 스토어에서 제공하는 고유 식별자입니다. 이는 각 개인에게 고유한 정보이기 때문에 기기에만 국한되지 않으며, 모바일 어트리뷰션에 유용합니다. Android 광고 ID는 iOS의 IDFA와 비슷합니다. 모바일 어트리뷰션은 모바일 앱 설치를 원래 출처(예: 광고 캠페인 또는 앱 스토어 검색)에 귀속시킵니다. 사용자는 광고 ID를 비활성화하도록 선택할 수 있으며, 어린이를 대상으로 한 앱은 전혀 추적할 수 없습니다.
Android 광고 ID를 사용하려면 다음 단계를 따르십시오.
2022년 4월 1일부터 Google은 사용자가 광고 ID 추적을 거부할 수 있도록 허용합니다. 광고 ID가 null이나 오류를 반환할 수 있습니다. 앱 세트 ID라는 대체 ID를 사용할 수 있습니다. 이 ID는 기기에 설치된 모든 앱에 대해 고유합니다. 자세한 내용은 Google의 광고 ID 문서를 참조하십시오.
play-services-ads-identifier을 종속성으로 추가하십시오.bashdependencies { implementation 'com.google.android.gms:play-services-ads-identifier:18.0.1' }AD_MANAGER_APP권한 Google 모바일 광고 SDK 버전 17.0.0 이상을 사용하는 경우AD_MANAGER_APP을AndroidManifest.xml에 추가해야 합니다.xml <manifest> <application> <meta-data android:name="com.google.android.gms.ads.AD_MANAGER_APP" android:value="true"/> </application> </manifest>ProGuard 예외 추가
Amplitude Android SDK는 Java Reflection을 사용하여 Google Play 서비스의 클래스를 사용합니다. Amplitude SDK가 Android 애플리케이션에서 작동하도록 하려면
play-services-ads의 클래스에 대해 이러한 예외를proguard.pro에 추가하십시오.-keep class com.google.android.gms.ads.** { *; }AD_ID권한Android 13 이상을 대상으로 앱을 업데이트하는 경우 ADID를
deviceId로 사용하려면 매니페스트 파일에 다음과 같이 Google Play 서비스 일반 권한을 선언해야 합니다.xml<uses-permission android:name="com.google.android.gms.permission.AD_ID"/>자세한 내용은 Google의 광고 ID 문서를 참조하십시오.
광고 ID를 장치 ID로 사용
광고 ID를 가져오도록 로직을 설정한 후, useAdvertisingIdForDeviceId을 활성화하여 광고 ID를 장치 ID로 사용하도록 설정하십시오.
val amplitude = Amplitude(AMPLITUDE_API_KEY, applicationContext) {
useAdvertisingIdForDeviceId = true
}
앱 세트 ID
앱 세트 ID는 기기에 설치된 각 앱의 고유 식별자입니다. 사용자가 앱을 제거할 때 앱 세트 ID를 수동으로 재설정하거나, 앱을 열지 않은 지 13개월 후에 자동으로 재설정합니다. Google은 강력한 분석을 거부하려는 사용자를 위해 광고 ID에 대한 개인 정보 보호 친화적 대안으로 앱 세트 ID를 설계했습니다.
앱 세트 ID를 사용하려면 다음 단계를 따르십시오.
play-services-appset을 종속성으로 추가합니다. 2.35.3 이전 버전의 경우'com.google.android.gms:play-services-appset:16.0.0-alpha1'을 사용합니다.bashdependencies { implementation 'com.google.android.gms:play-services-appset:16.0.2' }앱 세트 ID를 장치 ID로 사용하도록 설정합니다.
val amplitude = Amplitude(AMPLITUDE_API_KEY, applicationContext) {
useAppSetIdForDeviceId = true
}
장치 ID 생애주기 분석
SDK는 다음 순서로 장치 ID를 초기화하고 장치 ID를 발견한 첫 번째 유효한 값으로 설정합니다.
- 인스턴스의 장치 ID입니다.
- ADID(필수 모듈을 활성화하고
useAdvertisingIdForDeviceId설치하는 경우). 자세한 내용은 광고주 ID를 참조하십시오. - 필수 모듈을 활성화하고
useAppSetIdForDeviceId설치한 경우, 추가 내용이 포함된S앱 세트 ID입니다. 자세한 내용은 애플리케이션 세트 ID를 참조하십시오. R이 추가된 임의로 생성된 UUID.
한 명의 사용자가 여러 장치를 사용
단일 사용자는 각각 다른 장치 ID를 가진 여러 장치를 가질 수 있습니다. 일관성을 유지하려면 이러한 모든 장치에서 사용자 ID를 일관되게 설정하십시오. 장치 ID가 서로 다른 경우에도 Amplitude는 이를 단일 Amplitude ID로 병합하여 고유 사용자로 식별할 수 있습니다.
새 장치로 전송
사용자가 새 장치로 전환할 때 여러 장치가 동일한 장치 ID를 가질 수 있습니다. 사용자가 새로운 장치로 이동할 때 사용자는 종종 다른 관련 데이터와 함께 자신의 애플리케이션을 전송합니다. 전송되는 특정 콘텐츠는 애플리케이션에 따라 다릅니다. 일반적으로 앱과 관련된 데이터베이스 및 파일 디렉토리가 포함됩니다. 포함되는 정확한 항목은 앱의 설계와 개발자의 선택에 따라 달라집니다. 데이터베이스 또는 파일 디렉토리가 한 장치에서 다른 장치로 전송되는 경우에도 첫 사용 후 저장된 장치 ID가 여전히 존재할 수 있습니다. SDK가 초기화 다음 기간동안 해당 장치 ID를 검색하는 경우 다른 장치가 동일한 장치 ID를 사용하게 될 수 있습니다.
장치 ID 가져오기
현재 deviceId의 값을 얻으려면 헬퍼 메소드 getDeviceId()을 사용하십시오.
val deviceId = amplitude.getDeviceId()
장치를 설정하려면 사용자 지정 장치 ID를 참조하십시오.
위치 추적
Amplitude는 기본적으로 사용자 이벤트의 IP를 위치(GeoIP 조회)로 변환합니다. 앱의 자체 추적 솔루션 또는 사용자 데이터는 이 정보를 무시할 수 있습니다.
버전 1.20.7 이상에서의 위치 추적
버전 1.20.7부터 SDK는 기본적으로 위치 추적을 비활성화합니다. true(으)로 locationListening구성 옵션을 설정하여 위치 데이터를 추적하십시오. 활성화된 경우, Amplitude는 Android 위치 서비스(사용 가능한 경우)를 사용하여 기록된 이벤트에 특정 좌표(경도 및 위도)를 추가합니다. 위치 추적을 비활성화한 상태로 유지하려면 locationListening을(를) false(기본값)(으)로 유지하십시오.
val amplitude = Amplitude(AMPLITUDE_API_KEY, applicationContext) {
locationListening = true
}
ProGuard 난독화
ProGuard 난독화를 사용하는 경우 파일에 다음 예외를 추가하십시오.-keep class com.google.android.gms.common.** { *; }
사용자를 추적에서 해제합니다
사용자는 추적을 완전히 거부할 수 있으며, 이 경우 Amplitude는 사용자의 이벤트나 브라우징 기록을 전혀 추적하지 않습니다. OptOut은 사용자의 개인정보 보호 요청을 이행할 수 있는 방법을 제공합니다.
optOut가 true인 동안 Amplitude는 이벤트를 저장하거나 전송하지 않습니다.
// At initialization
val amplitude = Amplitude(AMPLITUDE_API_KEY, applicationContext) {
optOut = true
}
// At runtime
amplitude.optOut = true
amplitude.optOut = false // Re-enable tracking
푸시 알림 이벤트
Android SDK를 사용하여 클라이언트 측에 푸시 알림 이벤트를 전송하지 마십시오. 사용자가 앱을 열어 Amplitude SDK를 초기화해야 SDK가 이벤트를 전송할 수 있기 때문에, SDK는 다음에 사용자가 앱을 열 때까지 Amplitude 서버에 이벤트를 전송하지 않습니다. 이로 인해 데이터 지연이 발생할 수 있습니다.
import com.amplitude.common.Logger
import com.amplitude.core.LoggerProvider
class sampleLogger : Logger {
override var logMode: Logger.LogMode
get() = Logger.LogMode.DEBUG
set(value) {}
override fun debug(message: String) {
TODO("Handle debug message here")
}
override fun error(message: String) {
TODO("Handle error message here")
}
override fun info(message: String) {
TODO("Handle info message here")
}
override fun warn(message: String) {
TODO("Handle warn message here")
}
}
class sampleLoggerProvider : LoggerProvider {
override fun getLogger(amplitude: com.amplitude.core.Amplitude): Logger {
return sampleLogger()
}
}
amplitude = Amplitude(AMPLITUDE_API_KEY, applicationContext) {
loggerProvider = sampleLoggerProvider()
}
다중 인스턴스
Amplitude의 여러 인스턴스를 생성할 수 있습니다. 동일한 instanceName을 가진 인스턴스는 스토리지와 ID를 공유합니다. 격리된 스토리지 및 ID의 경우 각 인스턴스에 대해 고유한 instanceName을 사용하십시오. 자세한 내용은 구성을 참조하십시오.
val amplitude1 = Amplitude("api-key-1", applicationContext) {
instanceName = "one"
}
val amplitude2 = Amplitude("api-key-2", applicationContext) {
instanceName = "two"
}
오프라인 모드
버전 1.13.0부터 Amplitude Android Kotlin SDK는 오프라인 모드를 지원합니다. SDK는 이벤트를 추적할 때마다 네트워크 연결을 확인합니다. 디바이스에 네트워크 연결이 있는 경우 SDK는 플러시를 예약합니다. 그렇지 않은 경우 이벤트를 스토리지에 저장합니다. 또한 SDK는 네트워크 연결의 변경 사항을 수신하고 장치가 다시 연결될 때 저장된 모든 이벤트를 플러시합니다.
이 기능을 활성화하려면 AndroidManifest.xml에 ACCESS_NETWORK_STATE 권한을 추가하십시오. 그렇지 않으면 SDK는 flushIntervalMillis 및 flushQueueSize에 따라 이벤트를 플러시합니다.
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
또한 자신만의 오프라인 로직을 구현할 수도 있습니다.
- 기본 오프라인 로직을 비활성화하려면
config.offline을AndroidNetworkConnectivityCheckerPlugin.Disabled로 설정하십시오. - 직접
config.offline토글하십시오.
이 내용이 도움이 되었나요?
For AI agents: a documentation index is available at /docs/llms.txt. Append .md to any page URL for markdown, or send Accept: text/markdown.