1. 整合神策分析 SDK

1.1. 引入外掛程式

在 project 級別的 build.gradle 文件中增加 android-gradle-plugin2 依賴：

buildscript {
    repositories {
        jcenter()
    }
    dependencies {
        classpath 'com.android.tools.build:gradle:3.5.3'
        //增加神策分析 android-gradle-plugin2 依賴
        classpath 'com.sensorsdata.analytics.android:android-gradle-plugin2:3.2.9'
    }
}
GROOVY

1.2. 引入 SDK

在主 module 的 build.gradle 檔案中應用 com.sensorsdata.analytics.android 外掛程式、增加 SDK 依賴：

apply plugin: 'com.android.application'
// 應用 com.sensorsdata.analytics.android 外掛程式
apply plugin: 'com.sensorsdata.analytics.android'

dependencies {
   // 增加 Sensors Analytics SDK 依賴
   implementation 'com.sensorsdata.analytics.android:SensorsAnalyticsSDK:4.2.3'
}
GROOVY
  • Android SDK 要求最低系统版本為 API 9（Android 2.3）
  • 目前，Android SDK ( aar 格式) 大小約為 300 KB
  • Android SDK 在 AndroidManifest.xml 中註冊了可能使用到的權限，具體的權限和用途可参考權限設定說明

2. 初始化神策分析 SDK

2.1. 取得專案數據接收網址

  • 每個專案都有單獨的數據接收網址
  • 請使用管理員帳號取得相應專案的數據接收網址

2.2. 初始化 SDK

在 Application 的 onCreate() 方法中 Main Thread 呼叫 SensorsDataAPI.startWithConfigOptions() 初始化 SDK：

String SA_SERVER_URL = "數據接收網址";

// 初始化設定
SAConfigOptions saConfigOptions = new SAConfigOptions(SA_SERVER_URL);
// 開啟全埋點
saConfigOptions.setAutoTrackEventType(SensorsAnalyticsAutoTrackEventType.APP_CLICK |
                SensorsAnalyticsAutoTrackEventType.APP_START |
                SensorsAnalyticsAutoTrackEventType.APP_END |
                SensorsAnalyticsAutoTrackEventType.APP_VIEW_SCREEN)
				//開啟 Log
				.enableLog(true);
/**
 * 其他設定，如開啟可視化全埋點
 */
// 需要在 Main Thread 初始化神策 SDK
SensorsDataAPI.startWithConfigOptions(this, saConfigOptions);
JAVA

3. 設定 Scheme

3.1. 取得專案 Scheme

  • 專案的 Scheme 需要使用管理員帳號取得
  • App 工程中可以同時設定多個專案的 Scheme

3.2. App 中增加 Scheme

取得 Scheme 後，在 AndroidManifest 檔案中的 Activity 標籤内設定 Scheme，以 MainActivity 為例：

<activity android:name=".MainActivity">
<!-- 在 MainActivity 中設定 Scheme-->
	<intent-filter>
		<action android:name="android.intent.action.VIEW" />
		<category android:name="android.intent.category.BROWSABLE" />
		<category android:name="android.intent.category.DEFAULT" />
		<data
			android:scheme="您專案的 Scheme 值" />
	</intent-filter>
</activity>
XML

設定 Scheme 時，intent-filter 需要單獨設定，不要和其他 intent-filter 混用。 Scheme 不能設定在含有 <action android:name="android.intent.action.MAIN" />  的 intent-filter 中，會導致應用無法打開。


4. SDK 基本設定

4.1. 開啟全埋點

初始化 SDK 時，setAutoTrackEventType() 方法可以設定需要開啟的全埋點類型。全埋點其他設定，可參考全埋點 (Android)。

4.2. 設定事件公共屬性

對於所有事件都需要增加的屬性，初始化 SDK 後，可以透過 registerSuperProperties() 將屬性註冊為公共屬性。設定方法如下:

// 將應用名稱作為事件公共屬性，後續所有 track() 追蹤的事件都會自動帶上 "AppName" 屬性
try {
    JSONObject properties = new JSONObject();
    properties.put("AppName", getAppName(this));
    SensorsDataAPI.sharedInstance().registerSuperProperties(properties);
} catch (JSONException e) {
    e.printStackTrace();
}
JAVA

公共屬性會保存在 App 本地快取中。可以透過 unregisterSuperProperty() 刪除一個公共屬性，或使用 clearSuperProperties() 刪除所有已設定的事件公共屬性。

4.3. 用戶登入

當用戶註冊成功或登入成功時，需要呼叫 SDK 的 login() 方法：

SensorsDataAPI.sharedInstance().login("登入 ID");
JAVA

為了準確記錄登入用戶的行為資訊，建議在以下時機各呼叫一次 login() 方法：

· 用戶在註冊成功時
· 用戶登入成功時
· 已登入用戶每次啟動 App 時

4.4. 記錄啟動事件

可以呼叫 trackInstallation() 方法記錄啟動事件，多次呼叫此方法只會在第一次呼叫時觸發啟動事件：

if(Build.VERSION.SDK_INT >=Build.VERSION_CODES.M){
    if (ActivityCompat.checkSelfPermission(this, "android.permission.READ_PHONE_STATE") != PackageManager.PERMISSION_GRANTED) {
        // 6.0 以上，無權限時，先申請 READ_PHONE_STATE 權限。
        ActivityCompat.requestPermissions(this, new String[]{"android.permission.READ_PHONE_STATE"}, 100);
    } else {
        // 6.0 以上，有權限時，直接觸發啟動事件。
        trackInstallation();
    }
} else {
    // 6.0 以下，無須申請權限，直接觸發啟動事件。
    trackInstallation();
}
JAVA

在權限回呼的 onRequestPermissionsResult() 方法中，申請權限結果回呼無論申請權限成功失敗，都要呼叫 trackInstallation()：

@Override
public void onRequestPermissionsResult(int requestCode, @NonNull String[] permissions, @NonNull int[] grantResults) {
    super.onRequestPermissionsResult(requestCode, permissions, grantResults);
    if (requestCode == 100) {
        // 申請權限結果回呼時（無論申請權限成功失敗），都需要觸發啟動事件。
        trackInstallation();
    }
}


/**
 * 記錄啟動事件
 */
private void trackInstallation() {
    try {
        JSONObject properties = new JSONObject();
		//這裡的 DownloadChannel 負責記錄下載商店的管道，值應傳入具體應用商店包的標記。如果沒有為不同商店打多管道包，則可以忽略該屬性的程式碼範例。
        properties.put("DownloadChannel", "XXX");
        // 觸發啟動事件
        SensorsDataAPI.sharedInstance().trackInstallation("AppInstall", properties);
    } catch (Exception e) {
        e.printStackTrace();
    }
}
JAVA

更多關於管道追蹤功能的說明，請參考渠道追蹤。

4.5. 程式碼埋點追蹤事件

SDK 初始化後，可以透過 track() 方法追蹤用戶行為事件，並為事件增加自定義屬性：

try {
    JSONObject properties = new JSONObject();
    properties.put("ProductID", 123456); 					// 設定商品 ID
    properties.put("ProductCatalog", "Laptop Computer"); 	// 設定商品類別
    SensorsDataAPI.sharedInstance().track("BuyProduct", properties);
} catch (JSONException e) {
    e.printStackTrace();
}
JAVA

事件名和事件屬性的格式規範，請參考數據格式。

5. 除錯查看事件資訊

初始化 SDK 時，進行以下設定，即可打開 SDK 的 log 輸出功能：

// 打開 SDK 的 log 輸出功能
saConfigOptions.enableLog(true); 
JAVA

在 Logcat 中篩選 SA. 關鍵詞：

  • 埋點事件觸發成功時，SDK 會輸出 track event 開頭的事件數據
  • 埋點事件觸發失敗時，SDK 會輸出相應的錯誤原因
  • 事件數據上報成功時，SDK 會輸出 valid message 欄位開頭的事件數據
  • 事件數據上報失敗時，SDK 會輸出 invalid message 欄位開頭的事件數據並輸出錯誤原因

6. SDK 可選設定

6.1. 設定用戶屬性

profileSet() 方法可以設定用戶屬性，同一個 key 被多次設定時，value 的值會進行覆蓋替換：

try {
    JSONObject properties = new JSONObject();
    // 設定用戶性別屬性 "Sex" 為 "Male"
    properties.put("Sex", "Male");
    // 設定用戶年齡屬性 "Age" 為 18
    properties.put("Age", 18);

    // 設定用戶屬性
    SensorsDataAPI.sharedInstance().profileSet(properties);
} catch (JSONException e) {
    e.printStackTrace();
}
JAVA

6.2. 打通 App 與 H5

版本要求

  • Android SDK v4.0.8 及以上版本
  • Android 外掛程式 v3.2.4 及以上版本

初始化 SDK 時，進行如下設定，即可開啟 App 打通 H5 功能

// 開啟 App 打通 H5
saConfigOptions.enableJavaScriptBridge(boolean isSupportJellyBean);
CODE

isSupportJellyBean：是否支援 API level 16 及以下的版本。打通功能透過 WebView 的 addJavascriptInterface() 方法實作，但在 API level 16 及以下的版本，addJavascriptInterface()  方法有安全漏洞，因此請謹慎使用。

打通功能需要 App 和 H5 同時開啟才可以生效，H5 開啟方法请参考 App 打通 H5。

6.3. 可視化全埋點

版本要求

  • 神策分析 v1.17.2517+
  • Android SDK v4.0.0+

SDK 初始化時，進行如下設定，即可開啟可視化全埋點：

// 開啟可視化全埋點
saConfigOptions.enableVisualizedAutoTrack(true);
JAVA