[Android] Amplitude SDK를 활용해 앱 내부 이벤트 트래킹 기능 구현하기
2024년 8월 14일에 작성되었던 글입니다.
1. Amplitude란
텍소노미(Taxonomy)
앱에서 수집할 이벤트와 속성을 명명 규칙(Naming Convention)과 카테고리로 체계적으로 정리한 것입니다.
이를 통해 여러 화면·기능에서 동일한 이벤트를 동일한 이름으로 추적해, 중복을 방지할 수 있습니다.
구성 요소는 다음과 같습니다.
- Event Name: 발생한 동작 (ex. "click_button", "complete_onboarding")
- Event Properties: 이벤트에 부가되는 정보 (ex. "page_name" → "signup", "button_name" → "next")
- User Properties: 유저 프로필 단위에서 기록하는 항목(ex. "user_email", "signup_date")
이벤트 트래커
앱 코드 내에서 이벤트 발생 시점을 잡아내어 분석 SDK(Amplitude, Firebase 등)로 전달하는 모듈입니다.
Amplitude Analytics
모바일·웹 애널리틱스 플랫폼으로, 이벤트 트래커를 통해서 사용자 행동 데이터를 수집·시각화·분석할 수 있습니다.
예시
다음과 같이 각 이벤트의 발생 시점, 정보, 전체 사용자 통계 등을 확인할 수 있습니다.
다음 예시는 Genti 앱의 사진 생성 과정에서 부모님 사진을 따로 떼어내어 한달간 지표를 확인해본 상황입니다.
2. Amplitude 초기세팅
(1) 프로젝트 설정
Amplitude에서 프로젝트를 생성하며, 개발서버의 테스트 과정이 전체적인 사용자 지표에 영향이 가지 않도록 방지하기 위해 두개의 프로젝트로 분리했습니다.
(2) amplitude Key 등록 및 의존성 추가
local.properties에 각 프로젝트의 api key를 등록한 후, 빌드 타입 별로 별도의 키를 등록합니다.
// build.gradle (Module)
android {
buildTypes {
debug {
buildConfigField("String", "BASE_URL", "\"${gradleLocalProperties(rootDir)["test.base.url"]}\"")
buildConfigField("String", "AMPLITUDE_KEY", "\"${gradleLocalProperties(rootDir)["amplitude.test.key"]}\"")
}
release {
buildConfigField("String", "BASE_URL", "\"${gradleLocalProperties(rootDir)["base.url"]}\"")
buildConfigField("String", "AMPLITUDE_KEY", "\"${gradleLocalProperties(rootDir)["amplitude.api.key"]}\"")
isMinifyEnabled = false
proguardFiles(getDefaultProguardFile("proguard-android-optimize.txt"), "proguard-rules.pro")
}
}
}
dependencies {
implementation("com.amplitude:analytics-android:1.17.3")
}(3) manifest 설정
사용자 기기의 정보를 획득하기 위해 READ_PHONE_STATE 권한을 추가해줍니다.
<uses-permission android:name="android.permission.READ_PHONE_STATE" />
3. Amplitude Manager 설정
AmplitudeManager 싱글톤은 앱 전체에서 하나의 인스턴스로만 Amplitude를 초기화·사용하도록 설계합니다.
object AmplitudeManager {
private lateinit var amplitude: Amplitude
/**
* 1) SDK 초기화: 앱 시작 시 Application.onCreate()에서 호출
* - apiKey: Amplitude 프로젝트 키
* - context: Application context 사용 권장
*/
fun init(context: Context, apiKey: String) {
amplitude = Amplitude(Configuration(apiKey, context.applicationContext))
}
/**
* 2) userId 설정: 로그인 후 호출하여 이벤트를 사용자별로 그룹화
*/
fun setUserId(userId: String) {
amplitude.setUserId(userId)
}
/**
* 3) 이벤트 전송:
* - eventName: 텍소노미에 정의된 이벤트 이름
* - properties1, properties2: 2단계로 나눠 속성을 전달
*/
fun trackEvent(
eventName: String,
properties1: Map<String, Any>? = null,
properties2: Map<String, Any>? = null
) {
val props = mutableMapOf<String, Any>()
properties1?.let { props += it }
properties2?.let { props += it }
if (props.isEmpty()) amplitude.track(eventName)
else amplitude.track(eventName, props)
}
/**
* 4) 사용자 속성 업데이트: Identify API 사용
*/
fun updateProperties(name: String, value: String) {
amplitude.identify(Identify().set(name, value))
}
fun updateIntProperties(name: String, value: Int) {
amplitude.identify(Identify().set(name, value))
}
fun incrementProperty(name: String) {
amplitude.identify(Identify().add(name, 1))
}
/**
* 5) 오류 이벤트 전송 : Throwable 형태 기록
*/
fun trackError(eventName: String, error: Throwable) {
trackEvent(eventName, mapOf("error" to error.message.toString()))
}
}이후 @HiltAndroidApp 또는 기본 Application에서 AmplitudeManager.init()을 호출해, 앱 전역에서 사용할 준비를 합니다.
@HiltAndroidApp
class MyApp : Application() {
override fun onCreate() {
super.onCreate()
...
initAmplitude()
}
private fun initAmplitude() {
AmplitudeManager.init(this, AMPLITUDE_KEY)
}
}
4. Taxonomy 설정
(1) Event 트래킹
다음과 같이 Taxonomy가 주어졌을 때, 생성해둔 AmplitudeManager를 통해서 트래킹을 진행할 수 있습니다.
1. Property가 존재하지 않는 경우
AmplitudeManager.trackEvent("complete_infoget")
2. Property가 존재하는 경우
AmplitudeManager.trackEvent(
EVENT_CLICK_BTN,
mapOf(PROPERTY_PAGE to "onboarding1"),
mapOf(PROPERTY_BTN to "exit"),
)
const val EVENT_CLICK_BTN = "click_button"
const val PROPERTY_PAGE = "page_name"
const val PROPERTY_BTN = "button_name"
3. 에러의 경우
fun getUserVerified() {
viewModelScope.launch {
runCatching {
// 서버통신
}.onSuccess {
// 성공 후 로직
}.onFailure { t ->
_rhythmSideEffect.emit(RhythmSideEffect.ErrorToast)
AmplitudeManager.trackError("error_get_user_verified", t)
}
}
}
4. 유저 로그 확인
(2) UserProperty 트래킹
다음과 같이 Taxonomy가 주어졌을 때, 생성해둔 AmplitudeManager를 통해서 트래킹을 진행할 수 있습니다.
AmplitudeManager.updateProperties("user_email", state.data.email)
AmplitudeManager.updateIntProperties("user_share", 0)
AmplitudeManager.plusIntProperties("user_share")- Identify().set(): 기존 값을 대체하며 저장합니다.
- Identify().add(): 정수 속성에 증감 연산을 수행합니다.
해당 유저의 정보를 프로퍼티를 통해 다음과 같이 확인할 수 있습니다.
이처럼 초기 설정, Manager 구현, Application 초기화, 텍소노미 관리, 사용자 속성 업데이트를 차례대로 구현하면, 일관성있고 확장성 높은 이벤트 트래킹 시스템을 구축할 수 있습니다.
참고 자료 :
Android Kotlin SDK - Amplitude Developer Center
[Amplitude] 앰플리튜드 SDK 개발 - 1. Quickstart