Android SDK

1. 대응 Android 버전

이 SDK는 Android2.2 이후의 환경에서 동작합니다.
※NDK(C/C++) 의 Crash 검출은 Android 2.3 이후에서 동작합니다.
※OpenGL ES의 화면캡쳐는 Android4.0 이후에서 동작합니다.

2. Android Project에 SDK를 임포트하는 방법

Step1:라이브러리 임포트

아래에서 SmartBeat SDK를 다운로드하고 unzip하십시오.

다른 형식의 SDK는 여기 에서 다운로드하십시오.

  • Android Studio
  • Eclipse + ADT
「smartbeat-android-<version>.jar」을 Project의 libs 폴더에 복사합니다.
(libs폴더가 존재하지 않을 경우에는、src폴더와 같은 계층에 신규로 작성합니다.)Project의build.gradle을 열어서, dependencies쪽에 아래의 내용을 추가함.

dependencies {
    compile fileTree(dir: 'libs', include: ['*.jar'])
}
「smartbeat-android-<version>.jar」을 Project의 libs 폴더에 복사합니다.
(libs폴더가 존재하지 않을 경우에는、src폴더와 같은 계층에 신규로 작성합니다.)

Step2:Permission의 정의

ProjectのAndroidManifest.xml을 열고、아래의 1줄을 추가합니다.
(이미 추가되어 있는 경우에는 불필요)

<uses-permission android:name="android.permission.INTERNET"/>

이것은 App안에서 발생한 Crash 데이터를 SmartBeat서버에 보내기 위해 최소한으로 필요한 권한입니다.

Step3:API키의 설정

Project의Application클래스를 계승한 클래스에 아래의 내용을 추가합니다.
(Application클래스를 계승한 클래스가 없을 경우에는 작성하고,
manifest 파일에 선언을 추가합니다.)

SmartBeat의 API를 이용할 수 있도록 Application클래스 아래에 import문을 추가합니다.

import com.smrtbeat.SmartBeat;

SmartBeat의 초기화 API를 Application클래스의 onCreate()에 추가합니다.
[API키]에 관해서는 콘솔보다 Project작성시에 발행된 키를 설정합니다.

public class MyApplication extends Application {
    @Override
    public void onCreate () {
        SmartBeat.initAndStartSession(this, "API키");
    }
}

Step4:유저 카운트 수 중복방지 설정

SDK버전 1.12이후

유저수의 집계에 광고ID를 사용하여 동일한 유저의 중복된 카운트를 방지합니다. 따라서 App의 재설치를 반복하더라도 불필요한 MAU(Monthly Active Users)수의 증가를 막을 수 있습니다.

※ 중복된 유저의 카운트를 막는 설정을 유효화하는 것으로 오디언스 기능도 유효화 됩니다.
※ 이 기능은 Google Play services 4.0이후의 버전이 설치된 단말을 사용하는 유저 카운트에만 유효합니다.(그 외의 유저는 기존대로 카운트됩니다.)

이 기능을 유효화하기 위해서는 아래의 순서대로 App에 Google Play services를 넣어 주세요. 이 기능을 유효화하지 않는 경우에는 아래의 순서가 불필요합니다.

  • Android Studio
  • Eclipse + ADT
Google Repository의 다운로드

Android SDK Manager에서 Google Repository를 설치해 주세요.
install_google_repository

build.gradle의 편집

App의 모듈의 build.gradle를 열고 아래와 같이 dependencies에 play-services를 추가해 주세요. 추가한 play-services의 버전은 최신버전(https://developers.google.com/android/guides/releases를 참조)을 지정해 주세요.

dependencies {
    compile fileTree(dir: 'libs', include: ['*.jar'])
    compile 'com.google.android.gms:play-services:8.4.0'
}

build.gradle편집 후에는 Android Studio툴바의 [Sync Project with Gradle Files] 버튼에서 편집결과를 프로젝트에 동기화해 주세요.

Google Play services 다운로드

Android SDK Manager에서 Google Play services를 설치해 주세요.
install_google_play_services

프로젝트의 추가

Eclipse에서 [File] -> [Import]로부터 [Existing Android Code into Workspace]를 선택、google-play-services_lib를 프로젝트에 임포트해주세요. google-play-services_lib는 Android SDK의 설치폴더 바로 아래의 폴더에 있습니다.

<android-sdk>/extras/google/google_play_services/libproject/google-play-services_lib

「Copy projects into workspace」의 체크는 ON으로 해 주세요.
import_google_play_services

라이브러리 추가

App의 프로젝트의 프로퍼티를 열고 [Android] 설정의 [Library] 항목에 있는 [Add...]버튼을 클릭하여 google-play-services_lib를 추가해 주세요.
library_google_play_services

manifest파일 편집

App의 manifest파일을 열고 <application>요소에 아래의 내용을 추가해 주세요.

<meta-data android:name="com.google.android.gms.version"
android:value="@integer/google_play_services_version" />
확인 방법
SDK버전 1.21이후

아래의 API를 호출하여 중복 사용자 계정 방지 설정이 정상적으로 적용되어 있는지 확인할 수 있습니다.

boolean ok = SmartBeat.isReadyForDuplicateUserCountPrevention();

위의 API가 false를 반환하는 경우, Google Play services가 올바르게 적용되어 있지 않을 가능성이 있습니다.

Step5:onResume, onPause의 등록(Android4.0보다 이전(API레벨 13이전)버전도 대상으로 할 경우에만)

각 Activity의 onResume(), onPause()에 아래의 코드를 추가해 주세요.

import com.smrtbeat.SmartBeat;

@Override
protected void onResume(){
    super.onResume();
    SmartBeat.notifyOnResume(this);
    //your code
}

@Override
protected void onPause(){
    super.onPause();
    SmartBeat.notifyOnPause(this);
    //your code
}

Step6:Proguard의 설정(Proguard 유효시에만)

Proguard를 유효화 할 경우, Proguard의 설정에 아래를 추가해 주세요.

-dontwarn com.smrtbeat.**
-keep class com.smrtbeat.** { *; }

일반적으로는 프로젝트의 루트에 있는 proguard-project.txt 또는 proguard-rules.pro를 편집해 주세요.

Step4의 유저카운트 중복방지 설정을 유효화한 경우에는 아래의 설정을 추가해 주세요.

-dontwarn com.google.android.gms.**

3. 옵션 기능

3.1 화면캡쳐 기능(비OpenGL ES)

본 기능을 유효화 하면 Crash 발생까지의 화면 이동 내역을 확인할 수 있습니다.
SDK에서는 App 표시중에 최신 화면을 정기적으로 캡쳐하고, Crash가 발생했을 경우,
최근 1장을 SmartBeat서버에 보냅니다.
※OpenGL ES로 드로잉 했을 경우, 3.2장을 참고해 주세요.

유효화 방법
Android4.0(API레벨 ver14)이후만을 대상으로 한 경우

아래의 코드를 Application클래스의 onCreate()에 구현하는 것만으로 유효화 됩니다.

SmartBeat.enableAutoScreenCapture();

이것을 구현하는 것으로 Activity의 onResume로부터 onPause까지의、스크린샷을 보존합니다.
또한、이 API을 API레벨 ver13이전에서는 호출가능하지만 동작은 하지 않습니다.

Android4.0보다 이전(API레벨13이전)도 대상으로 하는 경우

아래의 코드를 Application클래스의 onCreate()에 구현하고,

SmartBeat.enableAutoScreenCapture();

또한、각Activity의 onResume()、onPause()에 아래의 코드를 추가해 주세요.

@Override
protected void onResume(){
    super.onResume();
    SmartBeat.notifyOnResume(this);
    //your code
}

@Override
protected void onPause(){
    super.onPause();
    SmartBeat.notifyOnPause(this);
    //your code
}

위의 어느 방법을 사용하더라도 일부 처리를 빼고 내부에서 생성된 다른 스레드에 처리가 진행됩니다.
실제로 화면 취득 처리에 관해서만, UI스레드 상에서 실행됩니다.
현재, SurfaceView의 캡쳐는 지원되지 않습니다.

캡쳐대상 외로서 Activity를 등록

유저 개인정보의 입력을 다루는 화면 등、화면을 캡쳐하고싶지 않는 Activity가 있을 경우、아래와 같이 해당 Activity를 등록하는 것으로, 화면캡쳐 대상외로 지정할 수 있습니다.(아래는 MyActivity를 대상 외로 지정해 등록한 예)

SmartBeat.setActivityAsSensitive(MyActivity.class.getName());

3.2 화면캡쳐 기능(OpenGL ES)

이 기능을 유효화 하면、OpenGL ES에서 드로잉한 화면의 캡쳐기능을 유효화 할 수 있습니다.
SDK에서 、App표시중에 최신 화면을 정기적으로 내부 저장소에 최대 3화면을 보존하고, Crash가 발생했을 경우 SmartBeat서버에 보냅니다.
※1 본 기능은 Android4.0이상에서만 동작합니다.(4.0미만의 경우 구현에는 문제가 없지만 동작하지 않습니다.)
※2 기능은 OpenGL ES 2.0이상 이용할 경우에만 동작합니다.(1.x을 이용할 경우 구현에는 문제가 없지만 동작하지 않습니다.)
※3 본 기능은 Whitelist에 등록되어진 플랫폼만이 동작합니다. 제 6장 참고

유효화 방법

이 기능을 유효화하기 위해서는 다음으로 설명하게 되는 3개의 API호출을 구현할 필요가 있습니다.

OpenGL ES의 버전설정

GLSurfaceView를 계승한 클래스에서 onSurfaceCreated()를 오버라이드해서,
그 안에 SmartBeat.onSurfaceCreated(int version, boolean useStencilBuffer)를
호출해 주세요.
첫번째 파라미터의 int는、이용하고있는 OpenGL의 버전 입니다.。
※setEGLContextClientVersion(int version)에서 설정하고 있는 값과 같은 값을 설정해 주세요.
두번째 파라미터의 boolean은 StencilBuffer을 이용하고 있는 경우、true를 설정해 주세요.
true의 경우、캡쳐 대상의 OS버전은、Android4.3이후가 됩니다.

SmartBeat.onSurfaceCreated(버전 번호, 스텐실 버퍼 이용 유무);
OpenGL 드로잉 전후에서의 API의 호출

Android상에서 OpenGL의 드로잉 처리를 행할 전 후에 아래와 같이 API를 구현해 주세요.
구체적으로는、GLSurfaceView.Renderer를 계승할 클래스의 onDrawFrame(GL10 gl)안에 처음과 끝에 추가해 주세요.

@Override
public void onDrawFrame(final GL10 gl) {
    SmartBeat.beginOnDrawFrame();
    //실제 App의 드로잉 처리
    SmartBeat.endOnDrawFrame();
}
추가 API

또한、임의의 디바이스를 whitelist에 추가할 경우、아래의 API를 이용하여 추가할 수 있습니다.

SmartBeat.whiteListModelForOpenGLES(모델명);

[모델명]은 Android의 API(Build.MODEL)로부터 취득한 값을 설정합니다.
whitelist에 추가했지만 초기화에 실패했을 경우나 AndroidのOS버전이
지원되지 않을 경우에는 동작하지 않습니다.
정상적으로 동작하고 있는지 아닌지에 대해서는 beginOnDrawFrame()의 리턴값으로 확인할 수 있습니다.

3.3 캐치한 Exception의 보존

App이 캐치한 Exception을 기록할 수 있습니다.

유효화 방법
try{
    doSometingAndThrow();
} catch(MyException e){
    SmartBeat.logHandledException(getApplicationContext(), e);
}

또한 첫번째 파라미터의 Context를 취득할 수 없을 경우에는 null을 설정할 수 있습니다.
이러한 경우, 위치 정보의 설정과 네트워크 상태 등 Context를 필요로 하는 정보가 일부 포함되지 않습니다.

3.4 로그 출력

SDK버전 1.16이후

단말 로그에 출력하지 않고 로그를 수집할 수 있습니다.
※ 64KB미만일 경우 최대 500행, 그 외의 경우에는 64KB까지 최신 로그를 취득합니다.
※ 3.5장의 LogCat출력 기능을 유효로 한 경우, 이 기능에 의한 로그는 크래시 데이터에 포함되지 않고, LogCat의 로그만이 크래시 데이터에 포함됩니다.

유효화 방법

아래의 API호출을 실현하면 로그를 보존할 수 있습니다.

SmartBeat.log("message");

NDK(C/C++)로부터 로그를 출력할 경우에는 아래와 같은 함수를 준비하여 JNI의 기능을 사용해 위의 API를 호출해 주세요. SDK에 아래가 구현된 cpp파일이 포함되어 있습니다.

void SmartBeat_log(JNIEnv* env, const char* msg)
{
    jclass cls = env->FindClass("com/smrtbeat/SmartBeat");
    if (cls == NULL)
        return;
    jmethodID method = env->GetStaticMethodID(cls, "log", "(Ljava/lang/String;)V");
    if (method == NULL) {
        env->DeleteLocalRef(cls);
        return;
    }
    jstring str = env->NewStringUTF(msg);
    if (str == NULL) {
        env->DeleteLocalRef(cls);
        return;
    }
    env->CallStaticVoidMethod(cls, method, str);
    env->DeleteLocalRef(str);
    env->DeleteLocalRef(cls);
}

3.5 LogCat출력

LogCat의 출력을 Crash데이터에 포함할 경우에는 LogCat출력 기능을 유효화 해 주세요.
※ 64KB미만일 경우에는 최대 500행, 그 외의 경우에는 64KB까지 최신 로그를 취득합니다.
※ 이 기능을 유효로 할 경우, 3.4장의 로그 출력 API에 의한 로그는 크래시 데이터에 포함되지 않고, LogCat의 로그만이 크래시 데이터에 포함됩니다.

유효화 방법
SmartBeat.enableLogCat();

또한, 아래와 같이 필터링을 파라미터로 보내면 필터링된 로그만 취득할 수 있습니다.

SmartBeat.enableLogCat(“*:W”);

필터에 관한 상세 정보는 Android사이트를 참고해 주세요.
http://developer.android.com/tools/debugging/debugging-log.html#filteringOutput

또한, Android4.1 이전(API 레벨 15 이전)에 대해서는 LogCat 출력을 위해서 아래의 권한이 필요합니다.
Android4.1이후에는 Permission의 설정이 불필요하지만, 자신의 App이 출력한 Log만을 취득 가능합니다.

<uses-permission android:name="android.permission.READ_LOGS"/>

3.6 사용자ID 설정

대상 App이 관리하는 사용자를 식별할 ID가 이미 존재하는 경우, 기존의 것으로 설정할 수 있습니다.
설정된 사용자ID는 Crash와 함께 SmartBeat서버에 보내집니다.
어떤 사용자가 Crash를 발생시켰는지 등을 관리 콘솔상에서 확인할 수 있습니다.

유효화 방법

아래의 API호출을 구현하면 설정가능합니다.

SmartBeat.setUserId("user001");

3.7 확장 정보

Crash정보에 확장정보를 부여할 수 있습니다. App에 따라서는 사용자가 설정한 정보와 App이 내부에서 보존하고
있는 정보가 Crash해석에 도움을 줍니다.

유효화 방법

아래의 API호출을 구현하면 임의의 키 이름과 값을 세트로 Crash데이터와 함께 보존할 수 있습니다.

SmartBeat.addExtraData("key1", "value1");
SmartBeat.addExtraData("area", "Tokyo");

또한, 확장 정보를 HashMap을 사용해 여러개를 동시에 설정할 수 있습니다.

HashMap<String, String> map = new HashMap<String, String>();
map.put("key1", "value1");
map.put("area", "Tokyo");
SmartBeat.addExtraData(map);

값을 변경하고 싶은 경우에는, 같은 키 이름을 추가하면 새로운 값으로 덮어씌워집니다.

3.8 breadcrumb 기능

임의의 포인트로 breadcrumb를 남기면 에러가 발생할 때까지의 유저의 조작내용과 화면이동 등을 수집할 수 있습니다.

유효화 방법

기록을 남기고 싶은 장소에 아래의 API를 호출해 주세요.

SmartBeat.leaveBreadcrumbs("game scene 1");

breadcrumb는 가장 나중에 기록된 것을 포함해 16개 보존됩니다.
예를 들면, [맵 화면] → [게임 화면] → [설정 화면]등과, 키가 되는 화면의 이동시를 남길 경우, 에러 직전에
사용자가 어떻게 화면을 이동했는 지를 알 수 있습니다.

3.9 에러 수집 유효화・무효화 변경

SDK버전 1.6이후

초기 상태를 에러수집 무효화하고, 도중에 에러수집을 유효화하고싶을 경우에 이용할 수 있습니다.

유효화 방법

Ste3:API키의 설정에서 기술한 API를 대신해 아래의 API로 기동시에 유효화할지 무효화할지 설정할 수 있습니다.

public class MyApplication extends Application {
    @Override
    public void onCreate () {
        boolean enable = false; //무효 상태에서 기동하는 경우에는 false
        SmartBeat.initAndStartSession(this, "API키", enable);
    }
}

그 후, 유효화하고 싶을 경우에는 임의의 장소에 아래의 코드를 호출해 주세요.
호출된 이후에 발생한 에러가 수집됩니다.

SmartBeat.enable();

또한、유효화・무효화의 설정은 매 기동시에 initAndStartSession(Application app, String appKey, boolean enabled) 에서 설정해 주세요.

3.10 백그라운드 어플리의 기동시 통지에 대해

SDK버전 1.18이후

SmartBeat에서는 화면의 표시(Activity.onResume())을 어플리 기동으로 하고 있습니다.이 때문에 백 그라운드 동작이 메인이 되는 어플리에서는 유니크 유저가 적게 카운트 되어 크래쉬 율이 높게 표시되고 맙니다.
본API를 어플리 백그라운드 기동시에 처리 개시 타이밍에 불러오는 것으로 유니크 유저 수를 좀 더 정확하게 집계하는게 가능하게 되어 집니다.

3.11 심볼파일 자동 업로드

[.so Upload script]또는[.so Upload Jenkins plugin]을 빌드환경에 적용함으로써 매번 빌드를 작성할때 자동으로C/C++의 심볼파일을 업로드 하는게 가능합니다.

자세한 내용은, 각각 제공되는 스크립트 안의 readme 파일을 확인 해 주세요.

업로드 대상
  • NDK
  • CMake
업로드 대상 폴더는 어플리케이션의 Android프로젝트의libs폴더를 지정해 주세요.
업로드 대상의 폴더는 어플리케이션 모듈의build/intermediates/cmake/{debug|release}/obj폴더(debug 또한 release는 적절한 방법을 선택)을 지정해 주십시오.

3.12 오디언스 기능

유저 식별자로서 Advertising ID for Android 또는 IDFA for iOS를 사용하여
애플리케이션을 이용하는 유저의 남여비와 연령분포를 확인할 수 있습니다.

중복된 유저의 카운트를 막는 설정을 유효화하는 것으로 오디언스 기능도 유효화 됩니다.
중복된 유저의 카운트를 막는 설정에 대해서는 여기를 참조해 주세요.

4. 그 외의 Permission

SmartBeat는 Crash로그를 수집할 때에 해석에 필요한 단말상태등을 주변정보와 함께 기록합니다.
이러한 정보안에는 권한의 부여가 필요한 것이 있습니다. SmartBeat는 권한이 없어
정보를 취득할 수 없을 경우에 "no permission"이라고 기록하지만, Permission을 부여해 주면 아래의 정보도 취득할 수 있습니다.

Permission名 취득가능 정보
android.permission.ACCESS_NETWORK_STATE NW접속상태

5. 리소스 소비

SDK도입에 따른 리소스 소비계측 결과를 아래와 같이 표시했습니다.

단말 항목 SDK 도입시 기본화면
캡쳐 유효
OpenGL ES화면
캡쳐 유효
Nexus7 (2012)
Android 4.4.2
메모리 소비량
CPU 부하
약 1.7MB 증가
증감 없음
약 4.3MB 증가
평균 약 6.4% 증가
약 5.3MB 증가
평균 약 4.4% 증가
Xperia AX
Android 4.1.2
메모리 소비량
CPU 부하
약 0.6MB 증가
증감 없음
약 5.0MB 증가
평균 약 3.0% 증가
약 5.9MB 증가
평균 약4.1% 증가
Xperia Ray
Android 2.3.4
메모리 소비량
CPU 부하
약 1.1MB 증가
증감 없음
약 3.4MB 증가
평균 약 9.0% 증가
지원 없음

※ 화면캡쳐를 유효로 한 경우, 화면의 화소수에 따라 메모리 소비량이 증가
※ 화면캡쳐를 유효로 한 경우, 화면 취득, 인코드 처리, 보존 처리가 들어가기 때문에 CPU 부하가 증가

6. OpenGL ES화면캡쳐대상 단말

OpenGL ES 화면캡쳐 기능의 지원대상을 기술합니다.

디바이스명 Build.MODEL 검증 OS
버전
SDK
버전
NEXUS 5 Nexus 5 4.4 1.8 -
AQUOS PAD SH-06F SH-06F 4.4.2 1.8 -
AQUOS ZETA SH-04F SH-04F 4.4.2 1.8 -
Xperia ZL2 SOL25 SOL25 4.4.2 1.8 -
Xperia Z1 SOL23 SOL23 4.4.2 1.13 -
Xperia Z1 f SO-02F SO-02F 4.4.2 1.13 -
HTC J butterfly HTL23 HTL23 4.4.4 1.13 -
isai LGL22 4.4.2 1.13 -
Galaxy S5 SM-G900K 5.0 1.14 -

7. 개정 이력

개정일 변경 사항
2014년 2월 4일 초판 발행
2014년 3월 17일 그 밖의 권한으로부터 ACCESS_FINE_LOCATION을 삭제
화면캡쳐 최대보존 수를 3장으로 변경
클라이언트 라이브러리 개정판과 같이 파일명을 변경
2014년 4월 28일 NDK(C/C++)의 대응버전 추가로 기입
2014년 5월 30일 OpenGL ES에서의 화면캡쳐를 대응, 설명 추가
2014년 6월 5일 Logcat 취득량의 제한사항 추가로 기입
2014년 6월 27일 [3.9 에러 수집 유효・무효 변경]을 추가로 기입(SDK버전 1.6 이후)
2014년 8월 29일 [3.8 breadcrumb 기능]을 추가로 기입
2014년 10월 23일 [3.2 화면 캡쳐 기능(OpenGL ES)]의 유효화 방법을 변경
[6. OpenGL ES 서포트 대상]의 대상단말 변경
2014년 11월 20일 스텐실버퍼 이용시의 설정을 추가기입
2015년 2월 10일 [6. OpenGL ES서포트 대상]의 대상단말 변경
2016년 1월 6일 [Step4:유저카운트 중복방지 설정]를 추가(SDK버전 1.12이후)
[Step6:Proguard의 설정(Proguard를 유효화 한 경우)]을 변경
2016년 3월 14일 [6. OpenGL ES화면캡쳐대상 단말]의 대상단말 변경
2016년 4월 8일 [6. OpenGL ES화면캡쳐대상 단말]의 대상단말 변경
2016년 4월 20일 [3.12 오디언스 기능]을 추가
2016년 11월 21일 [3.4 로그 출력]를 추가(SDK버전 1.16이후)
[3.5 LogCat출력]의 보충 설명을 추가
2017년 3월 29일 [2. Android Project에 SDK를 임포트하는 방법]에Android Studio에서순서를 추가
[3.10 심볼파일 자동 업로드]을 추가
2017년 4월 18일 [3.12 백그라운드 어플리의 기동시 통지에 대해]을 추가
2019년 3월 4일 [Step4:유저 카운트 수 중복 방지 설정]을 변경