Skip to main content

Android Agent 통합 가이드

Android Agent를 실제 서비스에 통합하기 위한 단계별 가이드입니다.

1. 에이전트 소개

EUM(End-User Monitoring) 에이전트는 사용자 경험을 모니터링하고 분석하기 위한 도구입니다. 이 에이전트를 통해 사용자는 End-User의 다양한 활동을 추적하고, 성능 데이터를 수집할 수 있습니다. 특히 End-User의 트래픽이 집중되는 지점을 식별하여 사용자가 NetFUNNEL의 가상 대기실을 효과적으로 적용할 수 있도록 지원함으로써, 트래픽 과부하를 방지하고 안정적인 서비스 제공할 수 있습니다.

1.1 최소 요구 사항

  • Android API Level: 22 (Lollipop 5.1) 이상

  • Kotlin: 1.9.0 이상

  • Java: 1.8 이상

1.2 외부 의존성

  • OkHttp3: 네트워크 통신 라이브러리

  • Kotlinx Serialization: 직렬화 라이브러리

2. 에이전트 설치

info

본 가이드는 Android Studio 환경을 기준으로 작성되었습니다.

2.1 에이전트 다운로드

에이전트 파일을 다운로드 합니다.

Download

2.2 AAR 파일 추가

다운로드한 .aar 파일을 프로젝트의 app/libs 디렉터리에 복사합니다.

project_root/
├── app/
│   └── libs/
│       └── eum-android-agent_latest.aar
└── gradle/

2.3 Gradle 설정

2.3.1 에이전트 종속성 추가

dependencies {
    implementation(files("libs/eum-android-agent_latest.aar"))
    ...
}

2.3.2 외부 라이브러리 추가

EUM 에이전트가 필요로 하는 외부 라이브러리를 추가합니다.

dependencies {
    // OkHttp3 dependency
    val okHttpVersion = "4.12.0"
    implementation("com.squareup.okhttp3:okhttp:$okHttpVersion")
    
    // Serialization dependency
    val serializationVersion = "1.6.3"
    implementation("org.jetbrains.kotlinx:kotlinx-serialization-json:$serializationVersion")
}

2.4 Manifest 설정

AndroidManifest.xml 파일에 인터넷 권한을 추가합니다.

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools">
    
    <uses-permission android:name="android.permission.INTERNET" />
    
</manifest>

3. 에이전트 초기화

EUM 에이전트는 앱 실행과 동시에 초기화되어야 합니다.

tip

Application 클래스의 onCreate()에서 초기화하면 앱 재시작 시에도 정확한 모니터링이 가능합니다.

3.1 Application 클래스 생성

EumApplication.kt
import android.app.Application
import com.stclab.sdkeum.EUM

class EumApplication : Application() {
    override fun onCreate() {
        super.onCreate()
        
        // EUM Initialization
        initializeEUM()
    }
    
    private fun initializeEUM() {
        EUM.initialize(
            application = this,
            clientId = "{TENANT_ID}",
            serverUrl = "undefined",
            settingUrl = "undefined",
            printLog = false,
            trackResource = true
        )
    }
}

3.2 Application 클래스 등록

AndroidManifest.xml에 Application 클래스를 등록합니다.

<application
    android:name=".EumApplication"
    android:allowBackup="true"
    android:icon="@mipmap/ic_launcher"
    android:label="@string/app_name"
    android:theme="@style/AppTheme">
</application>

3.3 초기화 파라미터 상세

파라미터타입설명필수기본값
applicationApplication

디바이스 정보 및 이벤트 수집을 위한 앱 컨텍스트

O-
clientIdString

EUM 클라이언트 ID

O-
serverUrlString

EUM 서버 주소

O-
settingUrlString

EUM 설정 파일 URL

O-
printLogBoolean

디버그 로그 출력 여부

Xfalse
trackResourceBoolean

리소스 이벤트 추적 활성화 여부

Xtrue

3.4 초기화 확인

초기화 성공

EUM      D  [EUM] [INI] EUM is on. Console displays EUM.
EUM      D  [EUM] [INI] Initialization Success.
EUM      D  [EUM] [INI] {"isSuccess":true,"version":"1.0.0"}

초기화 실패

EUM      D  [EUM] [INI] Initialization failed.
EUM      D  [EUM] [INI] {"isSuccess":false,"version":"1.0.0"}

4. 인터셉터 설정

리소스 이벤트와 네트워크 에러를 수집하려면 사용 중인 네트워크 라이브러리에 맞는 인터셉터를 추가해야 합니다.

note

세션, 화면, 소스 에러 이벤트는 초기화만으로 자동 수집됩니다.

4.1 HttpURLConnection

import com.stclab.sdkeum.intercept.HttpURLConnectionInterceptor

private fun executeRequest(url: String) {
    val urlConnection = URL(url).openConnection() as HttpURLConnection
    
    // Add EUM Interceptor
    HttpURLConnectionInterceptor().intercept(urlConnection)
    
    try {
        urlConnection.requestMethod = "GET"
        urlConnection.connect()
    } finally {
        urlConnection.disconnect()
    }
}
파라미터타입설명필수 여부
connectionHttpURLConnection

HTTP 연결 객체

O

4.2 OkHttp3

import com.stclab.sdkeum.intercept.OkHttpInterceptor
import okhttp3.OkHttpClient

val client = OkHttpClient.Builder()
    .addInterceptor(OkHttpInterceptor()) // Add EUM Interceptor
    .build()
파라미터타입설명필수 여부
chainInterceptor.Chain

OkHttp 요청/응답 체인

O

4.3 Retrofit2

import com.stclab.sdkeum.intercept.RetrofitInterceptor
import retrofit2.Retrofit
import retrofit2.converter.gson.GsonConverterFactory

val okHttpClient = OkHttpClient.Builder()
    .addInterceptor(RetrofitInterceptor()) // Add EUM Interceptor
    .build()

val retrofit = Retrofit.Builder()
    .baseUrl("https://api.example.com/")
    .client(okHttpClient)
    .addConverterFactory(GsonConverterFactory.create())
    .build()
파라미터타입설명필수 여부
chainInterceptor.Chain

OkHttp 요청/응답 체인

O

4.4 Volley

import com.stclab.sdkeum.intercept.VolleyInterceptor
import com.android.volley.Request
import com.android.volley.RequestQueue
import com.android.volley.toolbox.Volley

val requestQueue: RequestQueue = Volley.newRequestQueue(context)

// Request using the EUM interceptor
val interceptor = VolleyInterceptor(
    Request.Method.GET,
    "https://api.example.com/data",
    { response ->
        // Handle success response
    },
    { error ->
        // Handle error
    }
)

requestQueue.add(interceptor)

5. 추가 설정

5.1 ProGuard/R8 설정

앱 난독화 시 EUM 에이전트 클래스를 보호하려면 다음 규칙을 추가하세요:

proguard-rules.pro
# Protect EUM Android agent classes
-keep class com.stclab.sdkeum.** { *; }
-keepclassmembers class com.stclab.sdkeum.** { *; }

5.2 버전 확인

에이전트 버전을 확인하려면 다음 함수를 사용합니다:

val version = EUM.getVersion()
Log.d("EUM", "Agent version: $version")

FAQ

Q: 초기화 실패 시 어떻게 해야 하나요?

A: 다음 사항을 확인하세요:

  1. 인터넷 권한이 매니페스트에 추가되었는지 확인
  2. 서버 URL과 설정 URL이 올바른지 확인
  3. 네트워크 연결 상태 확인
  4. 클라이언트 ID가 유효한지 확인

Q: 특정 이벤트만 수집하고 싶어요

A: trackResource 파라미터를 false로 설정하면 리소스 이벤트 수집 및 네트워크 에러를 비활성화할 수 있습니다. 다른 이벤트는 필요에 따라 인터셉터를 추가하지 않으면 수집되지 않습니다.

Q: 프로덕션 환경에서 로그를 끄려면?

A: 초기화 시 printLog = false로 설정하거나 BuildConfig.DEBUG를 사용하여 디버그 빌드에서만 로그가 출력되도록 설정하세요.