Android SDK

1. 対応Androidバージョン

本SDKはAndroid2.2以降の環境にて動作します。
※NDK(C/C++)のクラッシュ検知はAndroid2.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"/>

これは、アプリ内で発生したクラッシュデータをSmartBeatサーバへ送信するため最低限必要なPermissionとなります。

Step3:APIキーの設定

ProjectのApplicationクラスを継承したクラスに以下の2つを追加する。
(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を使用することで、同一ユーザの重複カウントを抑止します。これにより、アプリの再インストールを繰り返す行為(俗に言う「リセマラ」)があった場合でも、不要なMAU(Monthly Active Users)数の増加を抑えることができます。

※ 重複ユーザカウントの抑止設定を有効にすることでオーディエンス機能も有効となります。
※ 本機能はGoogle Play services 4.0以降がイントールされた端末を使用するユーザカウントにのみ有効です(それ以外のユーザは従来通りカウントされます)。

本機能を有効にするためには、以下の手順でアプリにGoogle Play servicesを組み込んでください。本機能を有効にしない場合には、以下の手順は不要です。

  • Android Studio
  • Eclipse + ADT
Google Repositoryのダウンロード

Android SDK ManagerでGoogle Repositoryをインストールしてください。
install_google_repository

build.gradleの編集

アプリのモジュールの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」のチェックはオンにしてください。
import_google_play_services

ライブラリの追加

アプリのプロジェクトのプロパティを開き、「Android」の設定の「Library」の項目にある「Add...」ボタンをクリックしてgoogle-play-services_libを追加してください。
library_google_play_services

マニフェストファイルの編集

アプリのマニフェストファイルを開き、<application>要素に以下を追加してください。

<meta-data android:name="com.google.android.gms.version"
        android:value="@integer/google_play_services_version" />

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)

本機能を有効にすることで、クラッシュ発生までの画面遷移が確認できるようになります。
SDKでは、アプリケーション表示中の最新画面を定期的キャプチャし、クラッシュ時に最新の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では、アプリケーション表示中の最新画面を定期的に内部のストレージに最大3画面分保存し、クラッシュ時に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)を呼び出してください。
第1引数のintは、利用しているOpenGLのバージョンになります。
※setEGLContextClientVersion(int version)で設定している値と同じ値を設定してください。
第2引数の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();
    //実際のアプリケーションの描画処理
    SmartBeat.endOnDrawFrame();
}
追加API

また、任意のデバイスをwhitelistに追加する場合、以下のAPIを利用して追加可能です。

SmartBeat.whiteListModelForOpenGLES(モデル名);

「モデル名」はAndroidのAPI(Build.MODEL)から取得した値が設定できます。
whitelistに追加した場合でも初期化に失敗した場合、AndroidのOSバージョンが非サポートの場合などは動作しません。
正常に動作を開始することができたか、否かはbeginOnDrawFrame()の戻り値で確認することができます。

3.3 CatchしたExceptionの保存

アプリケーションがCatchしたExceptionを記録することができます。

有効化方法
try{
    doSometingAndThrow();
} catch(MyException e){
    SmartBeat.logHandledException(getApplicationContext(), e);
}

なお、第1引数の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の出力をクラッシュデータに含める場合は、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の出力のため、下記Permissionが必要となります。
Android4.1以降においては、Permissionの設定は不要ですが、自身のアプリが出力したLogのみが取得可能です。

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

3.6 ユーザID設定

対象のアプリケーションが管理するユーザを識別するIDが既にある場合、それを設定することができます。
設定されたユーザIDはクラッシュとともにSmartBeatサーバへ送信されます。どのユーザでクラッシュが発生したかなど管理コンソール上で確認が可能です。

有効化方法

以下のAPI呼び出しを実装することで、設定可能です。

SmartBeat.setUserId("user001");

3.7 拡張情報

クラッシュ情報に拡張情報を付与することができます。アプリケーションによっては、ユーザが設定した情報や、アプリケーションが内部に保持している情報が、クラッシュ解析に役立ちます。

有効化方法

以下のAPI呼び出しを実装することで、任意のキー名と値のセットをクラッシュデータと共に保存することが可能です。

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)機能

任意のポイントでパンくずを残すことにより、エラー発生までにユーザが行った操作や画面遷移などを収集することができます。

有効化方法

パンくずを落とす(記録を残したい)場所で以下のAPIを呼び出して下さい。

SmartBeat.leaveBreadcrumbs("game scene 1");

パンくずは最後に記録されたものから最大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をアプリのバックグラウンド起動時の処理開始のタイミングで呼び出すことで、ユニークユーザ数をより正確に集計することが可能となります。

SmartBeat.notifyRunning();

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は、クラッシュログ収集時に解析に必要な端末の状態など周辺情報も一緒に記録します。
それら情報の中にはPermissionの付与が必要な物があります。SmartBeatはPermissionがなく、情報の取得ができない場合、”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日 その他Permissionから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月27日 「2. AndroidのProjectへのSDKの取り込み方法」にAndroid Studioでの手順を追加
「3.11 シンボルファイル自動アップロード」を追加
2017年4月13日 「3.10 バックグラウンドアプリの起動の通知」を追加