# Android SDK自動収集ガイド

# 1、自動収集の紹介

TAシステムは、データ収集を自動化するインターフェースを提供し、ビジネス要件に応じて自動収集が必要なデータを選択することができます。

現在サポートしている自動収集イベントの種類は次のとおりです。

APPインストール、APPインストールログの記録
APP起動、バックグラウンドから起こす
APP終了、バックグラウンドへの移動、起動時間の収集
ユーザーのAPP内のページビュー（Activity）
ユーザーのAPP内のコントロールクリック
APPクラッシュ情報の記録

次に、各データの収集メソッドを詳しく紹介します。

# 2、自動収集の有効化

enableAutoTrackを呼び出して、自動収集機能を開きます:

List<ThinkingAnalyticsSDK.AutoTrackEventType> eventTypeList = new ArrayList<>();

//APPインストールイベント
eventTypeList.add(ThinkingAnalyticsSDK.AutoTrackEventType.APP_INSTALL);

//APP起動イベント
eventTypeList.add(ThinkingAnalyticsSDK.AutoTrackEventType.APP_START);

//APP終了イベント
eventTypeList.add(ThinkingAnalyticsSDK.AutoTrackEventType.APP_END);

//APPページビューイベント
eventTypeList.add(ThinkingAnalyticsSDK.AutoTrackEventType.APP_VIEW_SCREEN);

//APPコントロールクリックイベント
eventTypeList.add(ThinkingAnalyticsSDK.AutoTrackEventType.APP_CLICK);

//APPクラッシュイベント
eventTypeList.add(ThinkingAnalyticsSDK.AutoTrackEventType.APP_CRASH);

//自動収集有効化イベント
ThinkingAnalyticsSDK.sharedInstance(this, TA_APP_ID).enableAutoTrack(eventTypeList);

業務要件に応じて、自動収集のイベントを有効化します。

TIP

コントロールクリックイベントまたはフラグメントショーイベントを収集するには、自動収集プラグインを使用します。

パブリックイベントプロパティを設定する、またはカスタムゲストIDを設定するには、自動収集を有効にする前にsetSuperProperties()かidentify()を呼び出します。

コードサンプル:

// 初期化 SDK
ThinkingAnalyticsSDK.sharedInstance(this, "TA_APP_ID","TA_SERVER_URL");

// ゲスト ID設定
ThinkingAnalyticsSDK.sharedInstance(this, TA_APP_ID).identify("123456789ABCabc");

// パブリックイベント設定
try {
    JSONObject superProperties = new JSONObject();
    superProperties.put("Channel","B1");
    ThinkingAnalyticsSDK.sharedInstance(this, TA_APP_ID).setSuperProperties(superProperties);
} catch (JSONException e) {
    e.printStackTrace();
}

//パブリックイベント設定後，自动采集を再開
List<ThinkingAnalyticsSDK.AutoTrackEventType> eventTypeList = new ArrayList<>();
eventTypeList.add(ThinkingAnalyticsSDK.AutoTrackEventType.APP_INSTALL);
eventTypeList.add(ThinkingAnalyticsSDK.AutoTrackEventType.APP_START);
eventTypeList.add(ThinkingAnalyticsSDK.AutoTrackEventType.APP_END);
eventTypeList.add(ThinkingAnalyticsSDK.AutoTrackEventType.APP_VIEW_SCREEN);
eventTypeList.add(ThinkingAnalyticsSDK.AutoTrackEventType.APP_CLICK);
eventTypeList.add(ThinkingAnalyticsSDK.AutoTrackEventType.APP_CRASH);

ThinkingAnalyticsSDK.sharedInstance(this, TA_APP_ID).enableAutoTrack(eventTypeList);

# 3、自動収集イベントの詳細

# 3.1 APPインストールイベント

APPインストールイベントはAPPの実際のインストールを記録し、APP起動時にアップロードされます。イベントの時間トリガーはAPPのインストール後の最初の起動時間です。APPのアップグレードはインストールイベントを起こさないが、APPを削除して再インストールする時はインストールイベントがアップロードされます。

イベント名: ta_app_install

# 3.2 APP起動イベント

APP起動イベントは、ユーザーがAPPを起動したとき、またはバックグラウンドからAPPを起こしたときに発生します。

イベント名: ta_app_start
プリセットプロパティ:#resume_from_background、ブール型、APPはユーザーが起動したかバックグラウンドから起こしたかを表します。値trueはバックグラウンドから起こしたことを表し、falseは直接起動したことを表します。

# 3.3 APP終了イベント

APP終了イベントは、ユーザーがAPPを閉じたとき、またはAPPをバックグラウンドに移動したときに発生します。

イベント名: ta_app_end
プリセットプロパティ:#durationは数値型で、APPアクセスの時間(起動から終了まで)を表し、単位は秒です。

# 3.4 APPページビューイベント

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を実装することでプロパティを追加することができます。次の2つの方法をリライドすることで、ページビューイベントにページ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のURLSchemaとして使用し、ページビューイベントが発生する時に、プリセットプロパティ#urlを追加し、値は現在のページのURLSchemaになります。同時にSDKは前のページにジャンプするURLSchemaを取得できれば、プリセットプロパティ#referrerにフォワードアドレスとして追加します。

getTrackPropertiesの戻り値は、このページのページビューイベントのカスタムプロパティであり、ページビューイベントに自動的に追加されます。

2.FragmentのページビューイベントにはFragmentクラスに注釈@ThinkingDataFragmentTitleを追加することができます。

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

FragmentでScreenAutoTrackerインターフェイスを実装し、カスタムプロパティに#titleプロパティを追加します。

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

# 3.5 APPコントロールクリックイベント

APPコントロールクリックイベントは、ユーザーがコントロールをクリックしたときに発生します。

イベント名: ta_app_click
プリセットプロパティ:
#screen_nameは文字列型で、コントロールが属するActivityのパッケージ名、クラス名です。
#titleは文字列型で、コントロールが属するActivityのタイトルであり、値はActivityのtitleプロパティ値です。
#element_contentは文字列型で、コントロールの内容です。
#element_typeは文字列型で、コントロールタイプです。
#element_idは文字列型で、コントロールのID、デフォルトでandroid: idを使用します。
#element_positionは文字列型で、コントロールにpositionがある場合のみアップロードします。
#element_selectorは文字列型で、コントロールviewPathのつなぎです。

以上のViewのクリックイベントには、分析値を拡張するために、多くのプロパティを設定するメソッドがあります。

# 3.5.1 カスタムコントロールID

コントロールのIDはデフォルトで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はコントロールIDを設定する必要があるviewです。パラメーターviewIDは設定されたコントロールIDです。コントロールのクリックイベントをアップロードするとき#element_idの値は受信値になります。

# 3.5.2 カスタムコントロールクリックイベントのプロパティ

次のメソッドで、あるコントロールクリックイベントにカスタムプロパティを追加することができます。

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

パラメーターviewはコントロールIDを設定する必要があるviewです。パラメーターproperties(JSONObject型)は設定されたコントロールIDです。コントロールのクリックイベントをアップロードするとき、これらのプロパティが追加されます。

また、ExpandableListView、ListView、GridViewは、Adapterインターフェイスの実装を通して、itemをクリック時のカスタムプロパティを追加することができます。

ExpandableListViewはをインターフェイスThinkingExpandableListViewItemTrackPropertiesを実装する必要があります。

public interface ThinkingExpandableListViewItemTrackProperties {
    /**
     * groupPosition、childPositionのitemクリック時のプロパティの追加
     * @param groupPosition
     * @param childPosition
     * @return
     * @throws JSONException
     */
    JSONObject getThinkingChildItemTrackProperties(int groupPosition, int childPosition) throws JSONException;

    /**
     * groupPositionのitemクリック時のプロパティの追加
     * @param groupPosition
     * @return
     * @throws JSONException
     */
    JSONObject getThinkingGroupItemTrackProperties(int groupPosition) throws JSONException;
}

ListViewとGridViewはインターフェイスThinkingAdapterViewItemTrackPropertiesを実装する必要があります。

public interface ThinkingAdapterViewItemTrackProperties {
    /**
     * groupPositionのitemクリック時のプロパティの追加
     * @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の注釈によるコントロールクリックイベントのアップロード

android: onclickをコントロール（view）とし、クリックイベントを追加する呼び出しメソッドを使用する場合、呼び出しメソッドに注釈@ThinkingDataTrackViewOnClickを追加することができます。この呼び出しメソッドが実行された時にSDKがコントロールクリックイベントをアップロードします。

@ThinkingDataTrackViewOnClick
public void buttonOnClick(View v){}

buttonOnClickが呼び出されると、コントロールクリックイベントをアップロードします。

# 3.6 APPクラッシュイベント

APPは未捕獲エラーが発生すると、APPクラッシュイベントをアップロードします。

イベント名: ta_app_crash
プリセットプロパティ:
#app_crashed_reason、文字型、クラッシュ時のスタックトラックを記録します。

# 4、自動收集事件の無視

次のメソッドで、ページまたはコントロールの自動収集イベントを無視します。

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

一部のページ(Activity)で、自動収集イベント(ページビューやコントロールクリックイベントを含む)を転送したくない場合は、次のメソッドで無視することができます。

//单一ページの無視
ThinkingAnalyticsSDK.sharedInstance(this, TA_APP_ID).ignoreAutoTrackActivity(MainActivity.class);

//複数ページの無視
List<Class<?>> classList = new ArrayList<>();
classList.add(MainActivity.class);
ThinkingAnalyticsSDK.sharedInstance(this, TA_APP_ID).ignoreAutoTrackActivities(classList);

ActivityまたはFragmentの前に注釈@ThinkingDataIgnoreTrackAppViewScreenを追加することでActivityあるいはFragmentのページビューイベントを無視します。

//TestActivityのページビューイベントを無視
@ThinkingDataIgnoreTrackAppViewScreen
public class TestActivity extends AppCompatActivity {
    ...
}

Activity前に注釈@ThinkingDataIgnoreTrackAppViewScreenAndAppClickを追加し、Activityページビューイベントとページのコントロールクリックイベントを無視します。

//TestActivityのページビューイベントとページのコントロールクリックイベントを無視
@ThinkingDataIgnoreTrackAppViewScreenAndAppClick
public class TestActivity extends AppCompatActivity {
    ...
}

# 4.2 コントロールクリックイベントの無視

ある種類のコントロールクリックイベントを無視するには、次のメソッドを使用します。

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

ignoredClassはDialog、Checkboxなど無視したいコントロールの種類です。

# 4.3 要素のクリックイベントの無視

ある要素(View)のクリックイベントを無視するには、次のメソッドを使用します。

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

targetViewは無視したいViewです。

# 5、注釈による効率的なイベント設定

あるメソッドの呼び出し回数を監視したい、またはあるメソッドが呼び出されるとイベントをアップロードする必要がある場合は、注釈@ThinkingDataTrackEventでアップロードしたいイベントを素早く設定することあできます。プロパティは変数に渡されないため、シンプルなイベントアップロードのみに適します。

//注釈を使用
@ThinkingDataTrackEvent(eventName = "event_name", properties = "{\"paramString\":\"value\",\"paramNumber\":123,\"paramBoolean\":true}")
public void fun(){}

この時点でメソッドfunが呼び出された場合、event_nameというイベントがアップロードされ、イベントのプロパティは"paramString":"value"と"paramBoolean": trueです。

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

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

APP起動イベント(ta_app_start)のプリセットプロパティ

プロパティ名	日本語	説明
#resume_from_background	バックグラウンドから起こすか	APPが起動されたかバックグラウンドから起こされたかを示す。trueはバックグラウンドから起こす。falseは直接に起動する。

APPクローズイベント(ta_app_end)のプリセットプロパティ

プロパティ名	日本語	説明
#duration	イベントの長さ	アプリの起動から終了までの時間を秒単位で表す。

APPページビューイベント(ta_app_view)のプリセットプロパティ

プロパティ名	日本語	説明
#title	ページタイトル	コントロールが属する Activity のタイトルの値。値は Activity の title プロパティ値。
#screen_name	ページ名	コントロールが属する Activity のパッケージ名、クラス名。
#url	ページアドレス	現ページのアドレス。 getScreenUrl を呼び出してurlの設定を行う。
#referrer	フォワードアドレス	前ページのアドレスに戻る。 getScreenUrl を呼び出してurlの設定を行う。

APPコントロールクリックイベント(ta_app_click)のプリセットプロパティ

プロパティ名	日本語	説明
#title	ページタイトル	コントロールが属する Activity のタイトルの値。値は Activity の title プロパティ値。
#screen_name	ページ名	コントロールが属する Activity のパッケージ名、クラス名。
#element_id	要素ID	コントロールのID。デフォルトで android: id を使用。 setViewID で設定可能。
#element_type	要素の種類	コントロールタイプ
#element_selector	要素セレクタ	コントロールの viewPath のセレクタ
#element_position	要素の位置	コントロールの位置情報。コントロールに position プロパティがある場合のみアップロード。
#element_content	要素の内容	コントロールの内容。

APPクラッシュイベント(ta_app_crash)のプリセットプロパティ

プロパティ名	日本語	説明
#app_crashed_reason	異常情報	文字型で、クラッシュ時のスタック軌跡を記録

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

TIP

コントロールクリックイベントとフラグメントページビューイベントをスタートしたい時のみ、プラグインを統合する必要があります。

apply plugin: 'cn.thinkingdata.android'

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

2.0.0より前のバージョンのSDKを使用している場合は、古いバージョンのプラグインを使用してください:

apply plugin: 'com.thinkingdata.analytics.android'

buildscript {
    repositories {
        google()
        jcenter()
    }
    dependencies {
        classpath 'com.thinking.analyselibrary.plugin:android-gradle-plugin:1.2.0'
    }
}

lambda式をサポートしたい、また編集中のエラーを解決したい場合は、最新バージョンのプラグインを使用してください。統合したいsdkのバージョンを2.7.6以下になってはなりません。

apply plugin: 'cn.thinkingdata.android'

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

項目build.gradleブックにプラグイン関連のパラメーターを構成します。

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

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

編集ログを開きたい場合は、debug=trueを設定し、falseをデフォルトにします。

jar内のクラスのスキャンを無効にしたい場合は、disableJar=trueを設定し、falseをデフォルトにします。

あるパスのクラスをスキャンしたくない場合は、exclude=['cn.thinkingdata.android','android.support']を設定します。

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

`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);

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

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;
        }
    }
});

← プリセットプロパティとシステムフィールド Android SDKマルチインスタンスガイド →