imqa.document

Android SDK 설치 가이드

IMQA Android SDK v1.0.32 설치 및 설정 방법을 안내합니다.

Tip서비스 키 발급

IMQA 관리 계정 로그인 후 글로벌 관리 > 서비스 관리에서 새로운 서비스를 등록하고 발급된 서비스 키를 사용하여 설치하세요.

IMQA Android SDK 지원 사양
항목요구사항
Java version1.8 이상
min SDK24 이상
compile SDK (= target SDK)34 이상
Support LanguageJava, Kotlin
Gradle8.10.2 이상
Gradle Plugin (AGP)8.8.0 이상

IMQA Android SDK 설치

IMQA SDK는 애플리케이션의 런타임에 데이터를 수집하기 위해 설계되었습니다. 아래 방법을 따라 SDK를 설치하세요.

1. Gradle 설정

IMQA Android SDK는 Maven 저장소를 통해 제공됩니다. 프로젝트의 Gradle 설정 파일에서 SDK를 추가합니다.

1-1. 프로젝트 수준의 build.gradle 또는 settings.gradle

Groovy 또는 Kotlin DSL을 사용하는 경우 각각 아래와 같이 Maven 저장소를 추가합니다.

Groovy DSL

allprojects {
  repositories {
    maven {
      url 'https://nexus.imqa.io/repository/imqa-maven-releases/'
    }
  }
}

Kotlin DSL

repositories {
  maven {
    url = uri("https://nexus.imqa.io/repository/imqa-maven-releases/")
  }
}

1-2. 모듈(app) 수준의 build.gradle

애플리케이션의 dependencies 섹션에 IMQA SDK를 추가합니다.

Groovy DSL

dependencies {
  implementation 'io.imqa:imqa-android-sdk:1.0.32'
}

Kotlin DSL

dependencies {
  implementation("io.imqa:imqa-android-sdk:1.0.32")
}
TipTip

버전은 SDK의 최신 버전을 입력하세요.

1-3. aar 파일 직접 설치

애플리케이션 디렉토리 하위에 libs 디렉토리를 생성하고 imqa-android-sdk-버전-release.aar 파일을 복사 후 dependencies 섹션에 IMQA SDK를 추가합니다.

Groovy DSL

dependencies {
  implementation files('libs/imqa-android-sdk-1.0.32-release.aar')
}

Kotlin DSL

dependencies {
  implementation(files("libs/imqa-android-sdk-1.0.32-release.aar"))
}

1-4. Desugaring 적용

minSdkVersion 이 26 미만인 경우 디슈가링을 활성화해야합니다.

Groovy DSL

compileOptions {
  ...
  coreLibraryDesugaringEnabled true
}
dependencies {
    // For AGP 7.4+
    coreLibraryDesugaring 'com.android.tools:desugar_jdk_libs:2.0.3'
    // For AGP 7.3
    // coreLibraryDesugaring 'com.android.tools:desugar_jdk_libs:1.2.3'
    // For AGP 4.0 to 7.2
    // coreLibraryDesugaring 'com.android.tools:desugar_jdk_libs:1.1.9'
}

Kotlin DSL

compileOptions {
  ...
  isCoreLibraryDesugaringEnabled = true
}
dependencies {
    // For AGP 7.4+
    coreLibraryDesugaring("com.android.tools:desugar_jdk_libs:2.0.3")
    // For AGP 7.3
    // coreLibraryDesugaring("com.android.tools:desugar_jdk_libs:1.2.3")
    // For AGP 4.0 to 7.2
    // coreLibraryDesugaring("com.android.tools:desugar_jdk_libs:1.1.9")
}

2. Application 클래스 설정

IMQA SDK는 Application 클래스에 초기화 코드를 추가하여 동작합니다. Application 클래스의 onCreate() 메서드에서 다음을 설정하세요.

  1. Application 클래스 추가 애플리케이션의 AndroidManifest.xml 파일에 android:name 속성을 설정하여 Application 클래스를 지정합니다. 기존에 Application 클래스가 이미 존재하는 경우 이 단계를 생략할 수 있습니다.
<application
    android:name=".Application"
    ...
>
</application>
  1. SDK 초기화 코드 작성 Application 클래스의 onCreate() 메서드에 다음 코드를 추가합니다:

Kotlin

import io.imqa.sdk.core.IMQA
import io.imqa.sdk.core.IMQAOption

class Application : android.app.Application() {
    override fun onCreate() {
        super.onCreate()

        val options = IMQAOption()
        options.setDefault()
        options.setCollectorURL("여기에 url을 입력해주세요.")
        options.setServiceKey("여기에 service key를 입력해주세요.")
        options.setSampleRate("샘플링 비율(0.0~1.0) 값을 입력해주세요.") // default=0.5
        //대시보드 서비스 추가시 입력한 namespace를 넣어주세요
        options.setServiceNameSpace("Namespace")
        //배포 환경 설정 (선택 사항, 기본값: .PRODUCTION)
        //options.setEnvironment(Environment.DEVELOPMENT)
        // 클릭이벤트 자동 수집 설정 (default=false)
        //options.setUserEventEnable(true)

        IMQA.setup(options)
        IMQA.initialize(this.applicationContext, this)
    }
}

Java

import io.imqa.sdk.core.IMQA;
import io.imqa.sdk.core.IMQAOption;

public class Application extends android.app.Application {
    @Override
    public void onCreate() {
        super.onCreate();

        IMQAOption options = new IMQAOption();
        options.setDefault();
        options.setCollectorURL("여기에 url을 입력해주세요.");
        options.setServiceKey("여기에 service key를 입력해주세요.");
        options.setSampleRate("샘플링 비율(0.0~1.0) 값을 입력해주세요."); // default=0.5
        //대시보드 서비스 추가시 입력한 namespace를 넣어주세요
        options.setServiceNameSpace("Namespace"); 
        //배포 환경 설정 (선택 사항, 기본값: .PRODUCTION)
        //options.setEnvironment(Environment.DEVELOPMENT);        
        // 클릭이벤트 자동 수집 설정 (default=false)
        //options.setUserEventEnable(true)
        
        IMQA.setup(options);
        IMQA.initialize(this.getApplicationContext(), this);
    }
}
  • setCollectorURL: 데이터를 수집할 서버의 URL을 입력합니다.
  • setServiceKey: 발급받은 서비스 키를 입력합니다.
  • (option) setSampleRate: 샘플링 비율을 입력합니다. 샘플링 디폴트 값은 0.5(50%) 입니다.
    • 0.0~1.0 사이의 값을 입력합니다. (0.0 : 수집 안함, 1.0 : 100% 수집)

3. Https 설정
  1. Retrofit, OkHttp 설정

Retrofit, OkHttp 기반의 네트워크 요청의 XHR 데이터를 수집하기 위해 네트워크 요청 시 다음과 같이 HttpInterceptor를 추가해 주세요.

Kotlin

val client = OkHttpClient.Builder()
    .addInterceptor(HttpInterceptor())
    .build()

val retrofit = Retrofit.Builder()
    .baseUrl("https://api.example.com/")
    .client(client)
    .addConverterFactory(GsonConverterFactory.create())
    .build()

Java

OkHttpClient client = new OkHttpClient.Builder()
    .addInterceptor(new HttpInterceptor())
    .build();

Retrofit retrofit = new Retrofit.Builder()
    .baseUrl("https://api.example.com/")
    .client(client)
    .addConverterFactory(GsonConverterFactory.create())
    .build();
  1. HttpURLConnection 설정

HttpURLConnection 기반의 네트워크 요청의 XHR 데이터를 수집하기 위해 네트워크 요청 시 다음과 같이 추가해 주세요.

Kotlin

// HttpURLConnection(HttpsURLConnection) 객체를 ConnectionWrapper 로 감쌈
var url : URL = URL("https://some.host.com")
var conn = ConnectionWrapper.wrap(url.openConnection() as HttpURLConnection)

Java

// HttpsURLConnection(HttpsURLConnection) 객체를 ConnectionWrapper 로 감쌈
URL url = new URL("https://some.host.com");
HttpURLConnection conn = 
    ConnectionWrapper.wrap((HttpURLConnection) url.openConnection());
  1. Ktor(OkHttp) 설정

Ktor의 OkHttp 엔진을 사용하는 경우 네트워크 요청의 XHR 데이터를 수집하기 위해 네트워크 요청 시 다음과 같이 추가해 주세요.

Kotlin

val client = HttpClient(OkHttp) {
    engine {
        config {
            //타임아웃 등 기존 세팅
            connectTimeout(2, TimeUnit.SECONDS)
            readTimeout(2, TimeUnit.SECONDS)
            writeTimeout(2, TimeUnit.SECONDS)

            //Interceptor 추가
            addInterceptor(HttpInterceptor())
        }
    }
    install(Logging)

    install(ContentNegotiation) {
        json(Json { ignoreUnknownKeys = true })
    }
}

검증

IMQA가 정상적으로 동작하는지 확인하기 위해 샘플 오류를 발생시켜 로그가 전송되는지 확인합니다.

샘플 코드

아래 코드를 애플리케이션의 적절한 위치에 추가하여 테스트합니다.

Kotlin

import androidx.appcompat.app.AppCompatActivity
import android.os.Bundle
import java.lang.Exception
import io.imqa.sdk.log.IMQALog

class MainActivity : AppCompatActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        try {
            throw Exception("테스트 오류")
        } catch (e: Exception) {
            IMQALog.error("TestTag", "This is a test error", e)
        }
    }
}

Java

import androidx.appcompat.app.AppCompatActivity;
import android.os.Bundle;
import java.lang.Exception;
import io.imqa.sdk.log.IMQALog;

public class MainActivity extends AppCompatActivity {
    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);

        try {
            throw new Exception("테스트 오류");
        } catch (Exception e) {
            IMQALog.error("TestTag", "This is a test error", e);
        }
    }
}

IMQA Android SDK 설정

커스텀 사용자 ID 설정

커스텀 사용자 ID를 지정하여 특정 사용자의 세션 분석 시 활용할 수 있습니다. 일반적으로 로그인 성공 시 "사용자 아이디(또는 사번)"을 넣어주고, 로그아웃 성공 시 빈문자열("")을 설정해서 세션 분석을 진행합니다. IMQA.initialize 호출 이후에 실행되어야 정상적으로 동작합니다.

Kotlin

IMQA.custom.setupUserId("customer-user-id")

Java

IMQA.getCustomAttributes().setupUserId("customer-user-id");

custom-id

커스텀 이벤트 전송

특정 버튼이나 탭 버튼을 클릭 시 이벤트가 발생했음을 알리는 기능입니다.

IMQA.sendClickEvent(view: View, isNetworkRequest: Boolean = false)

  • view : 클릭 대상, isNetworkRequest : 데이터 조회 여부

단순히 화면 이동을 위한 버튼 클릭 시 이벤트 알림을 다음과 같이 전송할 수 있습니다.
클릭이벤트 자동 수집 옵션인 options.setUserEventEnable(true) 활성화시 중복으로 이벤트가 수집될 수 있습니다.

Kotlin

val intent = Intent(this, HelloActivity::class.java)
binding.button.setOnClickListener { startActivity(intent) }

IMQA.sendClickEvent(binding.button, false)

Java

Intent intent = new Intent(this, HelloActivity.class);
binding.button.setOnClickListener(v -> {
    startActivity(intent);
});
IMQA.sendClickEvent(binding.button, false);

버튼 클릭 시 서버로 데이터 조회를 할 경우 다음과 같이 전송할 수 있습니다.

Kotlin

binding.button.setOnClickListener {
    IMQA.sendClickEvent(it, true)
    service.getHello().enqueue(object : retrofit2.Callback<Data> {
        override fun onFailure(call: Call<Data>, t: Throwable) {
            t.printStackTrace()
        }

        override fun onResponse(call: Call<Data>, response: Response<Data>) {
            response.body()?.let { data ->
                IMQALog.debug("MainActivity", "Data: $data")
            }
        }
    })
}

Java

binding.button.setOnClickListener(new View.OnClickListener() {
    @Override
    public void onClick(View v) {
        IMQA.sendClickEvent(v, true);
        service.getHello().enqueue(new Callback<Data>() {
            @Override
            public void onResponse(Call<Data> call, Response<Data> response) {
                Data data = response.body();
                if (data != null) {
                    IMQALog.debug("MainActivity", "Data: " + data.toString());
                }
            }

            @Override
            public void onFailure(Call<Data> call, Throwable t) {
                t.printStackTrace();
            }
        });
    }
});

웹뷰 페이지 세션 연결

네이티브 앱의 세션과 웹뷰 내 페이지 세션을 하나로 결합하기 위해 webView.loadUrl(serverUrl) 호출전 JavaScriptInjector.injectSession(view) 코드를 사용하여 연결해야 합니다.

Tip하이브리드 앱(WebView 사용)에서의 IMQA 설정

IMQA Android SDK, iOS SDK, WebAgent는 각각 환경의 특성에 맞는 데이터를 수집합니다.

Kotlin

// ... 생략 ...
JavaScriptInjector.injectSession(webView)
webView.loadUrl(serverUrl)
// ... 생략 ...

Java

// ... 생략 ...
JavaScriptInjector.injectSession(webView);
webView.loadUrl(serverUrl);
// ... 생략 ...

Cordova Library Webview 설정

Cordova 라이브러리를 사용하는 경우 Webview를 다음과 같이 설정해야 합니다.

Cordova Library build.gradle

 
    compileOnly(files("libs/imqa-android-sdk-1.0.32-release.aar"))

Webview Interface 설정

JavaScriptInjector.injectSession(view) 코드를 사용하여 연결해야 합니다.

protected void init() {
   appView = makeWebView();
   createViews();
   if (!appView.isInitialized()) {
       appView.init(cordovaInterface, pluginEntries, preferences);
   }
   cordovaInterface.onCordovaInit(appView.getPluginManager());

   // WebView Interface 삽입 
   WebView realWebView = (WebView) ((SystemWebViewEngine) appView.getEngine()).getView();
   JavaScriptInjector.injectSession(realWebView);


   String volumePref = preferences.getString("DefaultVolumeStream", "");
   if ("media".equals(volumePref.toLowerCase(Locale.ENGLISH))) {
       setVolumeControlStream(AudioManager.STREAM_MUSIC);
   }
}

Fragment 라이프사이클

Fragment의 라이프사이클 이벤트(onCreate, onStart, onResume 등)를 자동으로 계측하여 화면 진입/이탈 시점을 추적할 수 있습니다.

Fragment 이름 난독화

난독화 도구에 따라 f.javaClass.simpleName 기반의 화면명이 변경될 수 있습니다. ProGuard/R8을 사용하는 경우에는 아래 규칙을 추가하여 Fragment 클래스 이름을 보존해 주세요. 단, ProGuard/R8 외의 다른 난독화 도구를 사용하는 경우 이름 보존 방식이 다를 수 있으므로 해당 도구의 가이드에 따라 별도 설정이 필요합니다.

ProGuard

-keepnames class * extends androidx.fragment.app.Fragment

Fragment 단위의 계측이 불필요한 경우, 초기화 시 옵션을 통해 비활성화할 수 있습니다.

options.setFragmentLifecycleEnabled(false)

사용자 커스텀 로깅

필요한 경우 SDK의 IMQALog API를 사용하여 사용자 로그를 수집할 수 있습니다. 로그 레벨은 debug, info, warn, error로 다음과 같이 사용하실 수 있습니다.

Important사용자 커스텀 로깅시 주의사항

사용자 커스텀 로깅 기능은 꼭 필요한 경우에 사용해 주세요. 무분별하게 너무 많은 로그를 남기면 앱에 성능 저하를 일으킬 수 있습니다. 또한, 수집 데이터가 늘어나므로 저장소 용량이 커질 수 있습니다.

Tip서비스에서의 중요한 로직과 거래 추적

문제 패턴과 예외 확인을 위한 커스텀 메시지를 남기고 식별할 수 있습니다.

Kotlin

IMQALog.debug("TAG", "message")
IMQALog.info("TAG", "message")
IMQALog.warn("TAG", "message")
IMQALog.error("TAG", "message", RuntimeException("exception"))

Java

IMQALog.debug("TAG", "message");
IMQALog.info("TAG", "message");
IMQALog.warn("TAG", "message");
IMQALog.error("TAG", "message", new RuntimeException("exception"));

수정하기