本文件概要說明 Android v3 專用的 Google Analytics (分析) SDK 部分進階設定。
總覽
Android 版 Google Analytics (分析) SDK 提供 Tracker
類別,可用於設定資料並傳送至 Google Analytics (分析),以及 GoogleAnalytics
單例模式,用來連結至導入項目的全域設定值。
初始化
必須先提供 Context
和 Google Analytics (分析) 資源 ID,才能透過 GoogleAnalytics
單例模式初始化至少一個追蹤器,才能開始評估資料:
// Initialize a tracker using a Google Analytics property ID. GoogleAnalytics.getInstance(this).getTracker("UA-XXXX-Y")
現在,這個追蹤程式可用於設定資料並傳送至 Google Analytics (分析)。
設定和傳送資料
系統會在追蹤器上設定參數/值組合的對應關係,並透過 set
和 send
方法傳送資料,藉此將資料傳送至 Google Analytics (分析):
/* * Send a screen view to Google Analytics by setting a map of parameter * values on the tracker and calling send. */ Tracker tracker = GoogleAnalytics.getInstance(this).getTracker("UA-XXXX-Y"); HashMap<String, String> hitParameters = new HashMap<String, String>(); hitParameters.put(Fields.HIT_TYPE, "appview"); hitParameters.put(Fields.SCREEN_NAME, "Home Screen"); tracker.send(hitParameters);
MapBuilder
類別簡化了建立命中程序,建議用於大多數用途。我們可以傳送相同的畫面檢視畫面,減少行數:
// Sending the same screen view hit using MapBuilder.createAppView() tracker.send(MapBuilder .createAppView() .set(Fields.SCREEN_NAME, "Home Screen") .build() );
Measurement Protocol Ampersand 語法
您也可針對單次命中設定值,方法是在 Builder
上設定值;針對所有後續命中值,則可使用 Measurement Protocol 與語法在追蹤程式物件上設定該值:
// Setting the content description field on a single hit using ampersand syntax. tracker.send(MapBuilder .createAppView() .set(Fields.SCREEN_NAME, "Home Screen") .build() );
如需可用 Measurement Protocol 參數的完整清單,請參閱 Measurement Protocol 參數參考資料。
將值套用至多次命中
系統會保留直接在追蹤程式上設定的任何值,並套用至多個命中,如以下範例所示:
// Set screen name on the tracker to be sent with all hits. tracker.set(Fields.SCREEN_NAME, "Home Screen"); // Send a screen view for "Home Screen" tracker.send(MapBuilder .createAppView() .build() ); // This event will also be sent with &cd=Home%20Screen. tracker.send(MapBuilder .createEvent("UX", "touch", "menuButton", null) .build() ); // Clear the screen name field when we're done. tracker.set(Fields.SCREEN_NAME, null);
請只在追蹤程式上直接設定想要在多次命中中保留的值。在追蹤程式上設定畫面名稱很合理,因為相同的值可套用至後續的畫面瀏覽和事件命中。不過,我們不建議您在追蹤程式上設定命中類型這類欄位,因為這個欄位可能會隨每次命中而改變。
使用多個追蹤器
單一導入方式可使用多個追蹤程式,這個方式在將資料傳送至多個資源時相當實用:
Tracker t1 = GoogleAnalytics.getInstance(this).getTracker("UA-XXXX-1"); // Trackers may be named. By default, name is set to the property ID. Tracker t2 = GoogleAnalytics.getInstance(this).getTracker("altTracker", "UA-XXXX-2"; t1.set(Fields.SCREEN_NAME, "Home Screen"); t2.set(Fields.SCREEN_NAME, getClass().toString()); // Send screen view to UA-XXXX-1. t1.send(MapBuilder .createAppView() .build() ); // Send screen view to UA-XXXX-2. t2.send(MapBuilder .createAppView() .build() );
自動評估功能 (例如自動螢幕和未偵測到的例外狀況評估) 只會使用一個追蹤器傳送資料至 Google Analytics (分析)。如果您正在使用這些功能,並希望使用其他追蹤器傳送資料,則必須手動進行。
使用預設追蹤器
Google Analytics (分析) 會保留預設追蹤程式。第一個初始化的追蹤器會成為預設追蹤程式,但可能會遭到覆寫:
// Tracker t1 becomes the default tracker because it is initialized first. Tracker t1 = GoogleAnalytics.getInstance(this).getTracker("UA-XXXX-1"); Tracker t2 = GoogleAnalytics.getInstance(this).getTracker("UA-XXXX-2"); // Returns tracker t1. Tracker defaultTracker = GoogleAnalytics.getInstance(this).getDefaultTracker(); // Hit sent to UA-XXXX-1. defaultTracker.send(MapBuilder .createAppView() .set(Fields.SCREEN_NAME, "Home Screen") .build() ); // Override the default tracker. GoogleAnalytics.getInstance(this).setDefaultTracker(t2); // Now this call returns tracker t2. defaultTracker = GoogleAnalytics.getInstance(this).getDefaultTracker(); // Hit sent to UA-XXXX-2. defaultTracker.send(MapBuilder .createAppView() .set(Fields.SCREEN_NAME, getClass().toString()) .build() );
取樣
您可以啟用用戶端取樣功能,限制傳送至 Google Analytics (分析) 的命中次數。如果應用程式的使用者人數較多,或是以其他方式傳送大量資料至 Google Analytics (分析),啟用取樣功能可確保報表資料不會中斷。
舉例來說,如果想透過 EasyTracker 和 XML 以 50% 的速率啟用用戶端取樣,請在 analytics.xml
檔案中使用以下參數:
<string name="ga_sampleFrequency">50.0</string>
如何以程式輔助方式啟用追蹤器的用戶端取樣功能:
mTracker.set(Fields.SAMPLE_RATE, 50.0d);
在應用程式層級選擇不採用
您可以啟用應用程式層級的選擇不採用標記,藉此停用整個應用程式的 Google Analytics (分析)。請注意,每次啟動應用程式時,都必須設定這個標記,並將預設值預設為 NO
。
如要取得應用程式層級的停用設定,請使用:
boolean isOptedOut = GoogleAnalytics.getInstance(this).getAppOptOut();
如要設定應用程式層級的選擇不採用功能,請使用:
GoogleAnalytics.getInstance(this).setAppOptOut(true);
在一般導入作業中,應用程式可能會監聽 SharedPreferences
的變更,並據此更新 Google Analytics (分析) 選擇不採用設定:
SharedPreferences userPrefs = PreferenceManager.getDefaultSharedPreferences(this); userPrefs.registerOnSharedPreferenceChangeListener(new SharedPreferences.OnSharedPreferenceChangeListener () { @Override public void onSharedPreferenceChanged(SharedPreferences sharedPreferences, String key) { if (key.equals(TRACKING_PREF_KEY)) { GoogleAnalytics.getInstance(getApplicationContext()).setAppOptOut(sharedPreferences.getBoolean(key, false)); } else { // Any additional changed preference handling. } } });
測試和偵錯
Android 版 Google Analytics (分析) SDK 提供多項工具,協助您輕鬆進行測試和偵錯。
模擬測試
SDK 提供 dryRun
旗標,設定後可防止任何資料傳送至 Google Analytics (分析)。每次測試或偵錯導入時,都應設定 dryRun
標記,但不希望測試資料顯示在 Google Analytics (分析) 報表中。
如要設定模擬測試標記,請按照下列步驟操作:
// When dry run is set, hits will not be dispatched, but will still be logged as // though they were dispatched. GoogleAnalytics.getInstance(this).setDryRun(true);
Logger
提供 Logger
介面,以處理 SDK 在這些詳細程度層級的實用訊息:error
、warning
、info
和 verbose
。
SDK 會初始化標準 Logger
實作,根據預設,系統只會將警告或錯誤訊息記錄到控制台。這些訊息會出現在 logcat 中。如要設定 Logger
的詳細程度:
// Set the log level to verbose. GoogleAnalytics.getInstance(this).getLogger() .setLogLevel(LogLevel.VERBOSE);
您也可以使用 Logger
的自訂實作項目:
// Provide a custom logger. GoogleAnalytics.getInstance(this).setLogger(new CustomLogger ());
完整範例
以下範例說明初始化 Google Analytics (分析) 導入作業,並傳送單一畫面檢視畫面所需的程式碼。
package com.example.app; import com.google.analytics.tracking.android.GAServiceManager; import com.google.analytics.tracking.android.GoogleAnalytics; import com.google.analytics.tracking.android.Tracker; import android.app.Application; import android.content.SharedPreferences; import android.preference.PreferenceManager; /* * An advanced Google Analytics implementation may be initialized * in a subclass of Application. Note that this example assumes data * only needs to be sent to a single Google Analytics property ID. */ public class MyApp extends Application { private static GoogleAnalytics mGa; private static Tracker mTracker; /* * Google Analytics configuration values. */ // Placeholder property ID. private static final String GA_PROPERTY_ID = "UA-XXXX-Y"; // Dispatch period in seconds. private static final int GA_DISPATCH_PERIOD = 30; // Prevent hits from being sent to reports, i.e. during testing. private static final boolean GA_IS_DRY_RUN = false; // GA Logger verbosity. private static final LogLevel GA_LOG_VERBOSITY = LogLevel.INFO; // Key used to store a user's tracking preferences in SharedPreferences. private static final String TRACKING_PREF_KEY = "trackingPreference"; /* * Method to handle basic Google Analytics initialization. This call will not * block as all Google Analytics work occurs off the main thread. */ private void initializeGa() { mGa = GoogleAnalytics.getInstance(this); mTracker = mGa.getTracker(GA_PROPERTY_ID); // Set dispatch period. GAServiceManager.getInstance().setLocalDispatchPeriod(GA_DISPATCH_PERIOD); // Set dryRun flag. mGa.setDryRun(GA_IS_DRY_RUN); // Set Logger verbosity. mGa.getLogger().setLogLevel(GA_LOG_VERBOSITY); // Set the opt out flag when user updates a tracking preference. SharedPreferences userPrefs = PreferenceManager.getDefaultSharedPreferences(this); userPrefs.registerOnSharedPreferenceChangeListener(new SharedPreferences.OnSharedPreferenceChangeListener () { @Override public void onSharedPreferenceChanged(SharedPreferences sharedPreferences, String key) { if (key.equals(TRACKING_PREF_KEY)) { GoogleAnalytics.getInstance(getApplicationContext()).setAppOptOut(sharedPreferences.getBoolean(key, false)); } } }); } @Override public void onCreate() { super.onCreate(); initializeGa(); } /* * Returns the Google Analytics tracker. */ public static Tracker getGaTracker() { return mTracker; } /* * Returns the Google Analytics instance. */ public static GoogleAnalytics getGaInstance() { return mGa; } }
接著,系統會在使用者看到第一個畫面時評估一次畫面瀏覽:
package com.example.app import android.app.Activity /** * A simple Activity that sends a screen view to Google Analytics * when it is displayed to the user. */ public class HomeScreen extends Activity { private static final String SCREEN_LABEL = "Home Screen"; @Override public void onCreate(Bundle savedInstanceState) { super.onCreate(savedInstanceState); // Fields set on a tracker persist for all hits, until they are // overridden or cleared by assignment to null. MyApp.getGaTracker().set(Fields.SCREEN_NAME, SCREEN_LABEL); } @Override public void onStart() { super.onStart(); // Send a screen view when the Activity is displayed to the user. MyApp.getGaTracker().send(MapBuilder .createAppView.build()); } }