imqa.document

Android Vanilla SDK 설치 가이드

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

TipIMQA 서비스 추가 > 앱 추가 > 키 발급

IMQA 관리 계정 로그인 후 관리 > 서비스 관리 메뉴에서 새로운 서비스를 추가합니다. 관리 > 앱 관리 메뉴에서 해당 서비스에 새로운 앱을 등록하고 발급된 앱 키를 확인합니다. 등록한 서비스 이름과 앱 키를 사용하여 설치하세요.

IMQA Android Vanilla SDK 지원 사양
항목요구사항
Java version1.8 이상
min SDK19 이상
Support LanguageJava, Kotlin

IMQA Android Vanilla SDK 설치

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

1. Gradle 설정

1-1. aar 파일 직접 설치

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

Groovy DSL

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

Kotlin DSL

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

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.android.sdk.core.IMQA
import io.imqa.android.sdk.core.IMQAOption
import io.imqa.android.sdk.core.IMQAOption.Environment
//import io.imqa.android.sdk.core.IMQAOption.DeviceIdType

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=1.0
        options.setServiceNameSpace("Namespace") 
        //options.setRemoteCollectionControlEnable(true)
        //options.setEnvironment(Environment.DEVELOPMENT)
        //options.setUserEventEnable(true)
        //options.setDeviceIdType(DeviceIdType.UUID)

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

Java

import io.imqa.android.sdk.core.IMQA;
import io.imqa.android.sdk.core.IMQAOption;
import io.imqa.android.sdk.core.IMQAOption.Environment;
//import io.imqa.android.sdk.core.IMQAOption.DeviceIdType;

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=1.0
        options.setServiceNameSpace("Namespace"); 
        //options.setRemoteCollectionControlEnable(true);
        //options.setEnvironment(Environment.DEVELOPMENT);        
        //options.setUserEventEnable(true);
        //options.setDeviceIdType(DeviceIdType.UUID);
        
        IMQA.setup(options);
        IMQA.initialize(this.getApplicationContext(), this);
    }
}
  • setCollectorURL: 데이터를 수집할 서버의 URL을 입력합니다.
  • setServiceKey: 발급받은 앱키를 입력합니다.
    (관리 > 앱 관리 > 앱키)
  • (option) setSampleRate: 샘플링 비율을 입력합니다. 샘플링 디폴트 값은 1.0(100%) 입니다.
    • 0.0~1.0 사이의 값을 입력합니다. (0.0 : 수집 안함, 1.0 : 100% 수집)
  • setServiceNameSpace: 대시보드 서비스 추가시 입력한 namespace를 넣어주세요.
    (관리 > 서비스 관리 > 서비스 이름) 또는 (관리 > 앱 관리 > 서비스)
  • (option)setEnvironment: 배포 환경 설정 (default: .PRODUCTION)
  • (option)setUserEventEnable: 클릭이벤트 자동 수집 설정(XML UI 지원) (default=false)
  • (option)setRemoteCollectionControlEnable: 원격 수집 제어 활성화 설정 (default=false)
    • SDK는 api로 전달된 서버 설정에 따라 적용됩니다.
    • On/Off (default=on)
    • 전송 실패 시 자동 중지 정책 (default=false)
    • 자동 중지 정책 실패 횟수 기준(default=5)
  • (option)setDeviceIdType: deviceId 타입 설정 (default=ANDROID_ID)
    • ANDROID_ID : 안드로이드에서 제공하는 식별자 (SSAID)
    • UUID: SDK 내부에서 생성되는 랜덤 식별자 (앱 삭제 후 재설치시 새로 생성)

3. Https 설정
  1. HttpClient 설정

HttpClient의 XHR 데이터를 수집하기 위해 setIMQAInterceptor 를 설정해야 합니다.

Kotlin

import io.imqa.android.sdk.network.httpclient.HttpClientInterceptor;
...
// DefaultHttpClient 에 HttpClientInterceptor 를 추가
val httpClient : DefaultHttpClient = DefaultHttpClient()
HttpClientInterceptor.setIMQAInterceptor(httpClient)
...

Java

import io.imqa.android.sdk.network.httpclient.HttpClientInterceptor;
...
// DefaultHttpClient 에 HttpClientInterceptor 를 추가
DefaultHttpClient httpClient = new DefaultHttpClient();
HttpClientInterceptor.setIMQAInterceptor(httpClient);
...
  1. Retrofit, OkHttp 설정

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

Kotlin

import io.imqa.android.sdk.network.okhttp.HttpInterceptor;
...
val client = OkHttpClient.Builder()
    .addInterceptor(HttpInterceptor()) //추가
    .build()
val retrofit = Retrofit.Builder()
    .baseUrl("https://api.example.com/")
    .client(client)
    .addConverterFactory(GsonConverterFactory.create())
    .build()
...

Java

import io.imqa.android.sdk.network.okhttp.HttpInterceptor;
...
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

import io.imqa.android.sdk.network.urlconnection.ConnectionWrapper;
...
// HttpsURLConnection 객체를 ConnectionWrapper 로 감쌈
var url : URL = URL("https://some.host.com")
var conn : HttpsURLConnection = 
    ConnectionWrapper.wrap(
    url.openConnection() as HttpsURLConnection
    ) as HttpsURLConnection
...

Java

import io.imqa.android.sdk.network.urlconnection.ConnectionWrapper;
...
// HttpsURLConnection 객체를 ConnectionWrapper 로 감쌈
URL url = new URL("https://some.host.com");
HttpsURLConnection conn = (HttpsURLConnection)
    ConnectionWrapper.wrap((HttpsURLConnection) url.openConnection());
...

4. 설치 검증

IMQA가 정상적으로 동작하는지 확인하기 위해 샘플 오류를 발생시켜 로그가 전송되는지 확인합니다. 아래 코드를 애플리케이션의 적절한 위치에 추가하여 테스트합니다.

Kotlin

import androidx.appcompat.app.AppCompatActivity
import android.os.Bundle
import java.lang.Exception
import io.imqa.android.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.android.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

import io.imqa.android.sdk.core.IMQA

IMQA.setCustomUserId("customer-user-id")

Java

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

IMQA.setCustomUserId("customer-user-id");

custom-id

커스텀 이벤트 전송

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

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

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

단순히 화면 이동을 위한 버튼 클릭 시 이벤트 알림을 다음과 같이 전송할 수 있습니다.

Kotlin

import io.imqa.android.sdk.core.IMQA

binding.button.setOnClickListener {
    IMQA.sendClickEvent(binding.button, false)
}

Java

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

binding.button.setOnClickListener(v -> {
    IMQA.sendClickEvent(v, 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.toString());
            }
        }
    })    
}

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 Interface 설정

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

Kotlin

import io.imqa.android.sdk.webview.JavaScriptInjector

JavaScriptInjector.injectSession(webView) //추가
webView.loadUrl(serverUrl)

Java

import io.imqa.android.sdk.webview.JavaScriptInjector;
// ... 생략 ...
JavaScriptInjector.injectSession(webView); //추가
webView.loadUrl(serverUrl);
// ... 생략 ...

사용자 커스텀 attribute 설정

사용자 정의 attribute 추가합니다.
사용자 attribute는 key 앞에 "custom."이 자동으로 추가됩니다.

Kotlin

import io.imqa.android.sdk.core.IMQA

IMQA.getCustomAttributes().setAttribute("key", "value")

Java

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

IMQA.getCustomAttributes().setAttribute("key", "value");

사용자 커스텀 로깅

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

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

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

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

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

Kotlin

import io.imqa.android.sdk.log.IMQALog

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

Java

import io.imqa.android.sdk.log.IMQALog;

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

수정하기