如何使用Android可視化埋點 - Quick Tracking

版本支援

可視化埋點SDK僅支援 android 4.0 及之上（api level >= 14）系統版本。在Android 4.0以下裝置上，可視化埋點功能無效。

SDK依賴

可視化埋點SDK必須與私人化統計SDK、私人化SPM外掛程式SDK配合使用。

請先參考私人化統計SDK 和私人化SPM外掛程式將對應SDK整合到您的應用中。

控制項支援列表

目前的版本可視化埋點SDK僅支援如下列表中控制項。未在列表中列出的控制項，尚未完成相容性測試，目前尚無法保證其有效性和準確性，對列表以外控制項類型進行埋點不保證相關資料能成功上報。

控制項	支援條件	備忘
android.widget.TextView	控制項clickable屬性為true時，才支援埋點以及日誌上報
android.widget.Button
android.widget.ImageButton
android.widget.CheckBox
android.widget.RadioButton
android.widget.ToggleButton
android.widget.Switch
android.view.View	支援埋點。但僅在控制項clickable屬性為true時，才支援日誌上報
android.widget.ImageView	控制項clickable屬性為true時，才支援埋點以及日誌上報
android.widget.ListView	支援ListView控制項Item埋點，包括Item為Layout子布局的情境，當Item包含子布局時，支援對子布局中單個控制項的埋點。
android.support.v7.widget.RecyclerView	支援RecyclerView控制項Item埋點，包括Item為Layout子布局的情境，當Item包含子布局時，支援對子布局中單個控制項的埋點。

SDK整合

SDK下載

SDK下載地址：Android SDK

SDK整合

將下載後的release.zip解壓，將解壓得到的兩個aar包，拷貝到宿主App目錄下libs目錄中（如果您的工程沒有此目錄則需要自己建立）。

Android Studio工程配置

宿主應用對應Module編譯指令碼 build.gradle 的 android 配置段中，需要添加如下配置：

repositories {
        flatDir {
            dirs 'libs'
        }
    }

宿主應用對應Module編譯指令碼 build.gradle 的 dependencies 配置段中，需要添加對應依賴：

可視化SDK必須搭配私人化統計SDK和SPM外掛程式才可使用，如您在可視化SDK包中未找到統計SDK和SPM外掛程式，請務必查看AndroidSDK 引入&配置SDK，完成相關包的引入。

         // 匯入私人化統計SDK和SPM外掛程式
    implementation files('libs/umeng-common-1.2.0.P.jar')
    implementation files('libs/umeng-spm-1.2.0.jar')

    // 匯入可視化埋點SDK
    // tracker-config包僅在埋點配置模式匯入，線上模式請切勿匯入此包！
    implementation files('libs/tracker-config-1.1.2.P.aar')
    implementation files('libs/tracker-release-1.1.2.P.aar')

tracker-release是使用可視化埋點功能必須匯入的包，必須引入。
tracker-config包僅在埋點配置模式依賴，線上正式發版App請切勿匯入此包！

許可權配置

需要在宿主App資訊清單檔AndroidManifest.xml中增加以下許可權聲明：

<uses-permission android:name="android.permission.INTERNET"/>
<uses-permission android:name="android.permission.READ_PHONE_STATE"/>
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE"/>

混淆配置

如果您的應用使用了代碼混淆，請添加如下配置，以避免可視化埋點SDK被二次混淆導致SDK不可用。

# SDK混淆配置（重要：啟用代碼混淆必須設定）

-keep class com.umeng.** {*;}

-keepclassmembers class * {
   public <init> (org.json.JSONObject);
}
-keepclassmembers enum * {
    public static **[] values();
    public static ** valueOf(java.lang.String);
}

SDK初始化

可視化埋點SDK無需額外初始化（統計SDK初始化函數UMConfigure.init內部會檢查宿主App是否已經匯入可視化埋點SDK，如果宿主App已經整合，會自動反射調用可視化埋點SDK初始化函數），按照私人化統計SDK初始化要求進行初始化即可。

統計SDK預初始化函數必須在宿主App的Application.onCreate函數主線程中執行：

public class MyApplication extends Application {
    @Override
    public void onCreate() {
        super.onCreate();

                // 設定收數網域名稱，注意：需要設定貴司自己的收數網域名稱
                UMConfigure.setCustomDomain("https://log-api.aplus.emas-poc.com", null);
        
        UMConfigure.setLogEnabled(true);
        // 預初始化, appkey和channel參數請修改為貴司App對應值
        final String useAppkey = "91547686";
        final String useChannel = "test_channel";

        // preInit預初始化函數必須在Application.onCreate函數主線程中執行。
        UMConfigure.preInit(this, useAppkey, useChannel);
        
        /**
         * 統計SDK初始化，注意：init初始化函數需要在客戶同意隱私授權協議之後調用
         */
        final Context appContext = this.getApplicationContext();
        final ScheduledThreadPoolExecutor executor = new ScheduledThreadPoolExecutor(1);
        executor.schedule(new Runnable() {
            @Override
            public void run() {
                Log.i(TAG, "--->>> 延遲5秒調用初始化介面：UMConfigure.init() ");
                UMConfigure.init(appContext, useAppkey, useChannel, UMConfigure.DEVICE_TYPE_PHONE, null);
            }
        }, 5, TimeUnit.SECONDS);
    }
}

控制項唯一性ID設定

對於APP中的每個所需上報日誌的控制項而言，都需要有一個可以唯一性識別該控制項的ID，便於在遍曆組件樹時能夠精準定位該控制項。設定控制項唯一性ID設定方法調用：

ViewTools.setViewId(View view, String id)

【重要】對於ListView，RecycleView等這類具有“瀑布流”特徵的控制項，為了減少業務方在可視化介面上的埋點配置，對於控制項中的各個組件設定統一ID，通過其位置資訊或者子控制項名稱進行區分，強烈推薦調用如下介面：

SDK提供以下兩個介面進行子ID設定

A. 通過position區分控制項

ViewTools.setViewId(View view, String id, int position)

如：RecycleView中的每個item項設定唯一ID。

B. 通過自訂子控制項名區分控制項

ViewTools.setViewId(View view, String id, String subViewId)

調試日誌

可視化埋點SDK模組完成初始化後，會列印相關日誌，日誌tag為"VTTracker"。日誌內容包含當前SDK工作模式。

Config Mode說明當前SDK工作在可視化埋點配置模式。此模式可以配合前端頁面埋點。

com.umeng.abtest I/VTTracker: Config Mode: SDK Init complete.

Release Mode說明當前SDK工作在可視化埋點線上模式。此模式下SDK拉取可視化埋點配置，可以在對應事件被觸發時發送統計日誌。

com.umeng.abtest I/VTTracker: Release Mode: SDK Init complete.

SDK整合Demo

Demo工程源碼：Android可視化埋點Demo

常見問題

1.在Activity或者Fragment頁面中如何埋點才能讓當前頁面支援可視化埋點功能？

只有在預先完成了手動PV埋點和SPM編碼埋點的Activity或者Fragment頁面中，才能支援本頁面的可視化埋點功能。

手動PV埋點和SPM編碼埋點範例程式碼：

@Override
    protected void onResume() {

        super.onResume();
        MobclickAgent.onPageStart("MainPage"); // 頁面手動PV埋點
        SpmAgent.updateCurSpm(this, "MainPage"); // SPM編碼設定

    }

@Override
    protected void onPause() {
    
        super.onPause();
        MobclickAgent.onPageEnd("MainPage"); // 頁面手動PV埋點
        
    }

沒有完成頁面手動PV埋點的頁面（調用MobclickAgent.onPageStart/onPageEnd完成手動PV埋點），如果試圖做可視化埋點，前端埋點頁面會提示頁面不匹配。

2.如何在正式發版前更好地去除配置版SDK？

應用在build.gradle檔案中經常會進行應用環境隔離配置，因此，建議在debug配置中引入tracker-configb包依賴，而在正式release配置中不引入該依賴即可。

3.是否支援ListView，RecycleView, Fragment等相對複雜的自訂控制項？

支援。需要注意的是，對於這些控制項在設定唯一性ID時，需要對子項中的某個具體控制項進行ID設定，而不是簡單的對整個控制項設定ID，如ViewToos.setViewId(listView, "listViewId")。

正確樣本

ListView樣本：

在自訂的ArrayAdapter的getView方法中設定ID，如：

@Override
    public View getView(int position, View convertView, ViewGroup parent) {
        //子view複用機制邏輯
        View view = convertView;
        if(view == null) {
            LayoutInflater inflater = LayoutInflater.from(mContext);
            View newView = inflater.inflate(R.layout.arrayadapter_item, parent, false);
            view = newView.findViewById(R.id.arrayadapter_text);
        }
        //更新子view內容
        ((TextView)view).setText(data[position]);
        //設定唯一id，可設定有業務含義的id name，本樣本直接使用常值內容
        ViewTools.setViewId(view, "統一id值", position);

        return view;
    }

RecycleView樣本：

自訂RecycleView.Adapter的ViewHolder，在onBindViewHolder方法中進行唯一性ID設定，如：

@Override
public void onBindViewHolder(final InfoViewHolder holder, int position) {
    if (getItemViewType(position)==TYPE_HEADER) {
        return;
    }
    final int pos=getRealPosition(holder);
    //mData緩衝網路資料
    String title = mData.get(pos).getTitle();
    //更新標題,holder.title為TextView
    holder.title.setText(title);
    //對hodler.title設定id
    ViewTools.setViewId(holder.title, "統一id值", position);
    
}

自訂VideoPlayer：

找到需要設定監聽的控制項，如播放按鈕，或播放視窗，設定ID

//jzvdStd為自訂的視頻播放控制項
//對開始按鈕設定id，id為url
ViewTools.setViewId(jzvdStd.startButton,"play_"+mData.get(pos).getVideoUrl());
//對播放視窗設定id
ViewTools.setViewId(jzvdStd.thumbImageView,"window_"+mData.get(pos).getVideoUrl());

4.如何記錄頁面PV？

可視化埋點SDK目前支援控制項的點擊 & 曝光事件採集，暫未開放PV採集功能，主要原因在於業務APP的頁面跳轉邏輯相對複雜，容易引發頁面pv記錄出錯問題。因此，對於頁面pv，建議業務方沿用已有的代碼pv埋點。

5.曝光預設規則是？

預設曝光條件為：

曝光面積超過/等於控制項面積的50%
曝光時間長度超過/等於500ms
曝光日誌合并發送
在一個頁面中，如果已經發生曝光，則不再重複曝光，直到發生以下操作：
頁面切換
關閉App，重新進入App
退至後台，重新進入App

[重點注意] 如何定義一個頁面？

在Android開發中，習慣性會以Activity定義一個頁面，可視化埋點SDK預設同樣採用Activity定義一個頁面。但實際情況中一個Activity中往往會有子頁面存在，如TabHost，Fragment等的使用，SDK預設只會發送一次曝光記錄。因此，如果業務方要求在一個Activity下的子頁中來回切換，曝光需要重新上報，可在子頁退出時，調用曝光資料重新整理介面進行重複曝光。

6.是否可以修改曝光規則中的曝光時間長度和曝光面積基準？

暫未提供該服務

7.如何驗證埋點是否正常，日誌上報是否正確？

在埋點設定階段，整合配置版SDK後，可在可視化頁面中點擊“查看埋點驗證日誌”，即可即時查看埋點及日誌上報情況。

8.可視化配置沒問題，但在發布APP中發現無法上報點擊日誌？（或瀑布流中list的item項無法上報日誌或list套list，裡層list的item項無法上報日誌）

主要原因在於唯一性ID設定的對象異常。檢查控制項點擊事件監聽邏輯，確認綁定了ID的控制項是否直接響應點擊，如果不是，需要將唯一性ID綁定在響應點擊事件的對象上。

例如，常見的listview中的item的布局為

<relativeLayout clickable="true">
<textview>
</textview>
</relativeLayout>

此時，layout對象處理了針對該item的點擊行為，並且該點擊事件並不會下傳到 textview 對象上，因此，如果將ID綁在textview上，則無法捕獲點擊行為，應相應的將ID綁定到 textview 對應的 layout 對象上。

再例如：TextView控制項需要設定android:clickable="true"屬性，否則預設情況下TextView可以支援可視化埋點，但是因為無法響應系統點擊事件，導致發布版本App中無法正常上報點擊日誌。