Android SDK自動収集ガイド

Android SDKはインストール、起動、クローズなどのイベントの自動収集が対応しております。

自動収集の紹介

TE システムで自動収集できる呼び出しは以下となります。

実際業務に応じてご利用ください。

1. インストールイベント（Install）：APPのインストール行動を記録
2. 起動イベント（Open APP）：APPを起動、またはバックグラウンドからAPPを起動
3. クローズイベント（Close APP）：APPをクローズまたはAPPがバックグラウンドに収める。同時に起動の時間経過を収集
4. 閲覧イベント（View Page）：APP内でページビュー（Activity）を閲覧
5. クリックイベント（Click）：APP内のコントローラ（view）をクリック
6. クラッシュイベント（Crash）：APPがクラッシュされた際の情報収集

これからそれぞれデータの収集メソッドについて紹介します。

自動収集を有効化

enableAutoTrackを呼び出しして、自動収集機能を有効化できます：

List<ThinkingAnalyticsSDK.AutoTrackEventType> eventTypeList = new ArrayList<>();
eventTypeList.add(ThinkingAnalyticsSDK.AutoTrackEventType.APP_INSTALL); //APP install event
eventTypeList.add(ThinkingAnalyticsSDK.AutoTrackEventType.APP_START); //APP enable event
eventTypeList.add(ThinkingAnalyticsSDK.AutoTrackEventType.APP_END); //APP disable event
eventTypeList.add(ThinkingAnalyticsSDK.AutoTrackEventType.APP_VIEW_SCREEN); //APP view screen event 
eventTypeList.add(ThinkingAnalyticsSDK.AutoTrackEventType.APP_CLICK); //APP click view event
eventTypeList.add(ThinkingAnalyticsSDK.AutoTrackEventType.APP_CRASH); //APP crash event
//enable autotrack event
ThinkingAnalyticsSDK.sharedInstance(this, TE_APP_ID).enableAutoTrack(eventTypeList);

::: Tips

コンローラーのクリックイベントもしくはFragmentの閲覧イベントを収集する場合は、自動収集プラグインを実装する必要があります。

:::

詳細紹介

3.1 インストールイベント（Install）

APPのインストールイベントを記録され、APPが起動時に送信します。イベントのトリガー時間はAPPインストール後の初回起動の時間となります。APPのバージョンアップはインストールイベントをカウントされませんが、削除したあとでの再インストールはカウントされます。

• イベント名：ta_app_install

3.2 起動イベント（Open APP）

APP起動イベントはユーザーがAPPを起動する時、またはバックグラウンドからAPPを起動する時に収集されます。

• イベント名：ta_app_start
• プリセットプロパティ：#resume_from_background、Boolean型で、APPが直接起動なのか、バックグラウンドからの起動なのかを記録します。trueはバックグラウンドからの起動で、falseは直接起動となります。
• 注意：V2.8.1からはSDKがデフォルトでバックグラウンドから暗黙起動（バックグラウンドでサービス起動やプッシュ）がトリガーしたstartイベントはできなくなります。必要に応じてres/valuesの下でta_public_config.xmlを追加して有効化にしてください。

<?xml version="1.0" encoding="utf-8"?>
<resources>
   <bool name="TAEnableBackgroundStartEvent">true</bool>
</resources>

3.3 クローズイベント（Close APP）

ユーザーがAPPをクローズする時、またはAPPをバックグラウンドに収める時に収集されます。

• イベント名：ta_app_end
• プリセットプロパティ：#duration、数値型で、APP起動の経過時間を統計されます。（単位：秒）

3.4 閲覧イベント（View Page）

APPでページ閲覧（Activity）をする時に収集されます。

• イベント名：ta_app_view
• プリセットプロパティ：

#screen_name、文字列型、Activityのパッケージ名とカテゴリ名

#title、文字列型、Activityのタイトル、Activityのtitleプロパティ値を取得

  閲覧イベントの中では他のプロパティを拡張して分析価値を高めることができます。以下は拡張方法となります。

3.4.1 自動収集でFragmentページ閲覧イベントを有効

android.support.v4.app.FragmentのFragment、以下の方法でページ閲覧イベントを収集できます。

SDK初期化完了後、以下の方法でFragmentの自動取集機能を呼び出しできます。

ThinkingAnalyticsSDK.sharedInstance(this, TA_APP_ID).trackFragmentAppViewScreen();

android.app.FragmentのFragmentは、以下の方法でできます。

ThinkingAnalyticsSDK.sharedInstance(this, TA_APP_ID).trackViewScreen(targetFragment);

• targetFragmentは閲覧イベント収集必要のFragmentに変更可能です。

3.4.2 カスタムページ閲覧イベントのプロパティ

Activityのページ閲覧イベントに対して、ScreenAutoTrackerの呼び出しを通してプロパティを追加することができます。以下二つの方法で、ページ閲覧イベントでページURL情報を追加や、その他のカスタムプロパティの追加が可能です。

public class MainActivity extends AppCompatActivity implements ScreenAutoTracker {
    private Context mContext;

    @Override
    public String getScreenUrl() {
        return "thinkingdata://page/main";
    }

    @Override
    public JSONObject getTrackProperties() throws JSONException {
        JSONObject jsonObject = new JSONObject();
        jsonObject.put("param1", "ABCD");
        jsonObject.put("param2", "thinkingdata");
        return jsonObject;
    }
}

その中で getScreenUrlのレスポンス値はActivityのURL　Schemaとして、該当ページの閲覧イベントが発生する時に、#urlというプリセットプロパティを追加で入れることができます。その同時にSDKは一個前のページのURL Schemaを取得します。取得可能の場合はプリセットプロパティ#referrerに追加されます。

getTrackPropertiesのレスポンス値は該当ページの閲覧イベントのカスタムプロパティで、Fragmentのページ閲覧イベントに対しては、下記2種のプロパティ追加方法があります。

• @ThinkingDataFragmentTitle を利用して追加

@ThinkingDataFragmentTitle(title = "myFragment")
public class ListViewFragment extends BaseFragment {
  // your fragment implementations
}

• ScreenAutoTracker 呼び出しで追加

  @Override
  public JSONObject getTrackProperties() {
      try {
          JSONObject properties = new JSONObject();
          properties.put("#title", "RecyclerViewFragment");
          return properties;
      } catch (JSONException e) {
          // ignore
      }
      return null;
  }

3.5 クリックイベント（Click）

APPのクリックイベントはコントローラ（view）をクリックする時に収集されます。

• イベント名：ta_app_click
• プリセットロプパティ：

#screen_name文字列型、viewが属しているActivityのパッケージ名＆カテゴリ名

#title文字列型、viewが属しているActivityのタイトルで、値はActivityのtitle

#element_content文字列型、viewの内容

#element_type文字列型、viewのタイプ

#element_id文字列型、viewのID、デフォルトでandroid:id

#element_position文字列型、viewにposition存在する時に収集

#element_selector文字列型、viewのviewPathのスプライシング

ページ上のViewのクリックイベントに対して、以下多種の方法でその他のプロパティを設定で、分析価値を高めることが可能です。

3.5.1 ViewIDを定義

viewIDはデフォルトでandroid:idを使用し、もしそのプロパティは取得できない場合、もしくはカスタムでIDを設定したい場合は、以下の方法で#element_idを書き換えられます。

ThinkingAnalyticsSDK.sharedInstance(this, TA_APP_ID).setViewID(view,viewID);

Dialogに対しては、以下の方法：

//android.app.Dialog
ThinkingAnalyticsSDK.sharedInstance(this, TA_APP_ID).setViewID(view,viewID);

もしくは

//android.support.v7.app.AlertDialog
ThinkingAnalyticsSDK.sharedInstance(this, TA_APP_ID).setViewID(view,viewID);

パラメータのviewはviewIDのviewで、パラメータviewIDのID、#element_idはクリックイベントを送信する時使用する値となります。

3.5.2 クリックイベントのプロパティを定義

以下の方法でコントローラ（view）のクリックイベントにカスタムプロパティを追加可能です。

ThinkingAnalyticsSDK.sharedInstance(this, TA_APP_ID).setViewProperties(view,properties);

パラメータのviewはカスタムプロパティのview、パラメータpropertiesはJSONObjectタイプで、カスタムプロパティとして、クリックイベント送信時に追加されます。

ExpandableListView、ListViewとGridViewはAdapterを通して特定のitemをクリック時のカスタムプロパティを追加することも可能です。

• ExpandableListViewはThinkingExpandableListViewItemTrackPropertiesの実現は呼び出しが必要

public interface ThinkingExpandableListViewItemTrackProperties {
    /**
     * Add properties when clicking items at groupPosition and childPosition
     * @param groupPosition
     * @param childPosition
     * @return
     * @throws JSONException
     */
    JSONObject getThinkingChildItemTrackProperties(int groupPosition, int childPosition) throws JSONException;

    /**
     * Add properties when clicking items at groupPosition
     * @param groupPosition
     * @return
     * @throws JSONException
     */
    JSONObject getThinkingGroupItemTrackProperties(int groupPosition) throws JSONException;
}

• ListViewとGridViewはThinkingAdapterViewItemTrackPropertiesインターフェースが必須

public interface ThinkingAdapterViewItemTrackProperties {
    /**
     * Add properties when clicking items in the position 
     * @param position
     * @return
     * @throws JSONException
     */
    JSONObject getThinkingItemTrackProperties(int position) throws JSONException;
}

3.5.3 AlertDialogのクリックイベントにページのActivity情報を追加

AlertDialogに対して（android.app.AlertDialogとandroid.support.v7.app.AlertDialog）のクリックイベントは、以下の方法で所属ページ（Activity）を紐付けて、プロパティに#screen_name と#title が追加されます。

• 以下の方法dialog.show()を呼び出して、dialog表示できます。

dialog.setOwnerActivity(targetActivity);

• 以下の方法builder.show()を呼び出して、dialog表示できます。

builder.show().setOwnerActivity(activity);

3.5.4 @ThinkingDataTrackViewOnClickの注釈でviewのクリックイベントを送信

もしandroid:onclickのviewを使用されている場合は、クリックイベントの呼び出し方法として、@ThinkingDataTrackViewOnClickの注釈で付け加えることで実現可能です。

@ThinkingDataTrackViewOnClick
public void buttonOnClick(View v){}

もしbuttonOnClickが呼び出しされた場合は、クリックイベントとして送信されます。

3.6 クラッシュイベント（Crash）

APPが予想外の異常がある際に、クラッシュイベントを収集されます。

• イベント名：ta_app_crash
• プリセットプロパティ：#app_crashed_reason文字列型で、クラッシュ発生時のスタックトレースを記録されます。

自動収取イベントを無視

以下の方法で、特定のページまたはviewの自動収集イベントを無視することができます。

4.1 ページの自動収集イベントを無視

特定ページのActivity　自動収集イベントで収集したくない場合（ページ閲覧とviewクリック）以下の方法で実現可能です。

//ignore a single screen
ThinkingAnalyticsSDK.sharedInstance(this, TA_APP_ID).ignoreAutoTrackActivity(MainActivity.class);
//ignore multiple screens
List<Class<?>> classList = new ArrayList<>();
classList.add(MainActivity.class);
ThinkingAnalyticsSDK.sharedInstance(this, TA_APP_ID).ignoreAutoTrackActivities(classList);

ActivityもしくはFragmentの前に@ThinkingDataIgnoreTrackAppViewScreen注釈を付け加えることで、特定のActivityもしくはFragmentのページ閲覧イベントを無視することも可能です。

//ignore the view screen event of TestActivity
@ThinkingDataIgnoreTrackAppViewScreen
public class TestActivity extends AppCompatActivity {
    ...
}

Activityの前に@ThinkingDataIgnoreTrackAppViewScreenAndAppClick注釈を付け加えることで、Activityの特定ページ閲覧イベントとイベントのviewクリックイベントを無視することができます。

//ignore the view screen event ofTestActivity as well as the view click event under the screen
@ThinkingDataIgnoreTrackAppViewScreenAndAppClick
public class TestActivity extends AppCompatActivity {
    ...
}

4.2 特定のタイプviewのクリックイベントを無視

特定のタイプviewのクリックイベントを無視したい場合は、以下の方法で実現可能です。

ThinkingAnalyticsSDK.sharedInstance(this, TA_APP_ID).ignoreViewType(ignoredClass);

• ignoredClassは無視したいviewのタイプDialog、Checkboxなど

4.3 特定のエレメントviewのクリックイベントを無視

特定のエレメントviewのクリックイベントを無視したい場合は、以下の方法で実現可能です。

ThinkingAnalyticsSDK.sharedInstance(this, TA_APP_ID).ignoreView(targetView);

• targetView は無視するView

注釈でイベントをクイック設定

特定の方法の呼び出し回数を監視したい場合、もしくは特定の方法で呼び出したあとですぐにイベントを送信したい場合は、@ThinkingDataTrackEvent注釈を利用してクイック設定可能です。プロパティにはシンプルイベントのみ対応しています。

//use annotation
@ThinkingDataTrackEvent(eventName = "event_name", properties = "{\"paramString\":\"value\",\"paramNumber\":123,\"paramBoolean\":true}")
public void fun(){}

もしその時にfunが呼び出された場合は、以下のイベントを自動で送信されます。

イベント名：event_name、プロパティ"paramString":"value"、"paramNumber":123 と "paramBoolean":true

自動収集イベントのプリセットプロパティ

以下のプリセットプロパティは、自動収集イベントの中で特有のプリセットプロパティとなります。

• APP 起動イベント（ta_app_start）のプリセットプロパティ

プロパティ名	名称	タイプ	説明
#resume_from_background	バックグラウンドから再開かどうか	文字列	APPの起動は直接起動なのか、バックグラウンドから再開なのか。trueはバックグラウンドから再開で、falseは直接起動となります。

• APP クローズイベント（ta_app_end）のプリセットプロパティ

プロパティ名	名称	タイプ	説明
#duration	イベント時間経過	数値	APP起動からの時間経過（起動からクローズ）、単位は秒

• APP 閲覧ページイベント（ta_app_view）のプリセットプロパティ

プロパティ名	名称	タイプ	説明
#title	ページタイトル	文字列	viewが属している Activity のタイトルで、 Activity の title プロパティで値を付与されます
#screen_name	ページ名称	文字列	viewが属している Activity のパッケージ名、カテゴリ名
#url	ページURL	文字列	現在ページのURL、 getScreenUrl を呼び出してURLの設定を行う必要があります。
#referrer	リファラー	文字列	本ページに移動する前のURLで、 getScreenUrl を呼び出して設定が必要です。

• APP viewクリックイベント（ta_app_click）のプリセットプロパティ

プロパティ名	名称	タイプ	説明
#title	ページタイトル	文字列	viewが属している Activity のタイトルで、 Activity の title プロパティで値を付与されます
#screen_name	ページ名称	文字列	viewが属している Activity のパッケージ名、カテゴリ名
#element_id	エレメント ID	文字列	viewのID、デフォルトで android:id を使用、 setViewID を呼び出しして設定可能です。
#element_type	エレメントタイプ	文字列	viewのタイプ
#element_selector	エレメントセレクター	文字列	viewの viewPath のスプライシング
#element_position	エレメント位置	文字列	viewの位置情報、viewが position プロパティが存在する時に送信されます
#element_content	エレメント内容	文字列	view上の内容

• APP のクラッシュイベント（ta_app_crash）のプリセットプロパティ

プロパティ名	名称	タイプ	説明
#app_crashed_reason	異常情報	文字列	クラッシュ発生時のスタックトレースを記録されます

自動収集機能プラグインの統合(任意)

::: Tips

viewクリックイベントと Fragmentページ閲覧イベントが有効した上で、オプションプラグインが実装可能になります。

:::

apply plugin: 'cn.thinkingdata.android'

buildscript {
    repositories {
        google()
        jcenter()
    }
    dependencies {
        classpath 'cn.thinkingdata.android:android-gradle-plugin2:1.0.5'
    }
}

プロジェクトbuild.gradleのファイルで関連のパラメータ設定を行えます

apply plugin: 'cn.thinkingdata.android'
android {

}
ThinkingAnalytics {
    debug = true
    disableJar = true
    exclude = []
    excludeSensitive = []
}

コンパイルログを開きたい場合はdebug = trueを設定してください。（デフォルトはfalse）

jar 内のクラスのスキャンを禁止したい場合はdisableJar = trueを設定してください。（デフォルトはfalse）

特定のパスの下にあるクラスをスキャンしたくない場合はexclude = ['cn.thinkingdata.android','android.support']を設定してください。

V1.0.5 以降、機密属性 (AndroidID など) を構成するためのコード分離ができます。excludeSensitive = ['AndroidID']をしてください。（SDKV2.8.1以上対応）

自動収集イベントのカスタムプロパティ設定

enableAutoTrack(List<ThinkingAnalyticsSDK.AutoTrackEventType>, JSONObject)を呼び出して、自動収集機能を有効にし、カスタムプロパティを同時に設定可能です。

JSONObject properties = new JSONObject();
try {
    properties.put("auto_self_define_key", "auto_self_define_value");
} catch (Exception e) {
    e.printStackTrace();
}
ThinkingAnalyticsSDK.enableAutoTrack(typeList, properties);

setAutoTrackProperties(List<ThinkingAnalyticsSDK.AutoTrackEventType>, JSONObject)を呼び出して、設定またはカスタムプロパティを更新できます。

JSONObject properties = new JSONObject();
try {
    properties.put("auto_self_define_key", "auto_self_define_value");
} catch (Exception e) {
    e.printStackTrace();
}
ThinkingAnalyticsSDK.setAutoTrackProperties(typeList, properties);

自動収集イベントのコールバックを設定

V2.7.5以降では、コールバックを設定することで、有効にした自動収集イベントが発生した際に現在のイベントのイベントタイプとイベントプロパティを取得でき、リスポンス値を設定することでイベントに付加値を追加で送信できます。

List<ThinkingAnalyticsSDK.AutoTrackEventType> typeList = new ArrayList<>();
typeList.add(ThinkingAnalyticsSDK.AutoTrackEventType.APP_START);
typeList.add(ThinkingAnalyticsSDK.AutoTrackEventType.APP_INSTALL);
typeList.add(ThinkingAnalyticsSDK.AutoTrackEventType.APP_END);

mInstance.enableAutoTrack(typeList, new ThinkingAnalyticsSDK.AutoTrackEventListener() {
    @Override
    public JSONObject eventCallback(ThinkingAnalyticsSDK.AutoTrackEventType eventType, JSONObject properties) {
        try {
            return new JSONObject("{\"keykey\":\"value1111\"}");
        } catch (JSONException e) {
            e.printStackTrace();
            return null;
        }
    }
});