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