本指南說明如何升級至 Android 版 Google Analytics (分析) SDK 第 3 版。
資訊一覽:第 3 版的新功能
第 3 版中的 API 已重構,以便在原生和網路平台上更加一致。所有 V2 使用者都應留意下列變更:
- 現在,系統會使用單一
send(Map<String, String> parameters)
方法傳送命中資料。 - 偵錯模式已替換為
Logger
- EasyTracker 現已將
Tracker
設為子類別,導致介面出現一些變更。 - 新增: 新增了
dryRun
標記,以免報表中出現傳送的資料。
如需完整異動清單,請參閱「 Android 變更記錄」。
事前準備
開始升級至第 3 版之前,您必須準備下列項目:
升級路徑
如要開始使用,請從目前的實作項目中選取升級至 v3 的路徑:
EasyTracker:v1.x 至 v3
我們建議 EasyTracker v1.x 使用者按照第 3 版入門指南的說明,開始搭配 EasyTracker 使用第 3 版。
EasyTracker:v2.x 至 v3
2.x EasyTracker 版本使用者必須按照下列步驟操作,完成升級至第 3 版:
- 將呼叫更新為
EasyTracker.getInstance()
以提供Context:
// v2 (Old) // EasyTracker.getInstance().activityStart(this);
// v3: EasyTracker.getInstance(this).activityStart(this);
EasyTracker
現在將Tracker
設為子類別 -- 移除對EasyTracker.getTracker()
的呼叫:// v2 (Old) Tracker v2Tracker = EasyTracker.getInstance().getTracker();
// v3 Tracker v3Tracker = EasyTracker.getInstance(this);
- 請將所有
send<hit-type>
便利方法替換為新的send(Map<String, String> parameters)
方法:// v2 (Old) Tracker v2EasyTracker = EasyTracker.getInstance().getTracker(this); v2EasyTracker.sendView("Home Screen");
// v3 Tracker v3EasyTracker = EasyTracker.getInstance(this); // Set the screen name on the tracker so that it is used in all hits sent from this screen. v3EasyTracker.set(Fields.SCREEN_NAME, "Home Screen"); // Send a screenview. v3EasyTracker.send(MapBuilder .createAppView() .build() );
進一步瞭解如何在第 3 版中傳送資料。 - 將
ga_debug
EasyTracker 參數替換為ga_logLevel
,以及下列其中一個詳細程度值:verbose
、info
、warning
、error
:<!-- res/values/analytics.xml --> <?xml version="1.0" encoding="utf-8"?> <resources> <string name="ga_trackingId">UA-XXXX-Y</string> <!-- REMOVE: <bool name="ga_debug">true</bool> --> <string name="ga_logLevel">verbose</string> </resources>
詳情請參閱 EasyTracker 參數參考資料。 GoogleAnalytics.requestAppOptOut()
已淘汰,請改用GoogleAnalytics.getAppOptOut()
:// v2 (Old) GoogleAnalytics.getInstance(this).requestAppOptOut(new AppOptOutCallback() { @Override public void reportAppOptOut(boolean optOut) { if (optOut) { ... // Alert the user that they've opted out. } }); }
// v3 boolean optOutPreference = GoogleAnalytics.getInstance(this).getAppOptOut();
- (選用) 在測試實作時,新增
ga_dryRun
EasyTracker 參數並設為true
,以免測試資料顯示在實際工作環境報表中:
<!-- res/values/analytics.xml --> <?xml version="1.0" encoding="utf-8"?> <resources> <string name="ga_trackingId">UA-XXXX-Y</string> <string name="ga_logLevel">verbose</string> <!-- Prevent data from appearing in reports. Useful for testing. --> <bool name="ga_dryRun">true</bool> </resources>
自訂導入:v1.x 至 v3
未使用 EasyTracker
的 1.x 使用者應遵循《V3 入門指南》,並視需要參閱進階設定開發人員指南。
自訂導入:從 v2.x 到 v3
未使用 EasyTracker
的 v2.x 使用者,請按照下列步驟完成升級至 v3:
- 將所有「send<hit-type>」便利方法替換為新的
send(Map<String, String> parameters)
方法:// v2 (Old) Tracker v2Tracker = GoogleAnaytics.getInstance(this).getTracker("UA-XXXX-Y"); v2Tracker.sendView("Home Screen");
// v3 Tracker v3Tracker = GoogleAnaytics.getInstance(this).getTracker("UA-XXXX-Y"); // This screen name value will remain set on the tracker and sent with // hits until it is set to a new value or to null. v3Tracker.set(Fields.SCREEN_NAME, "Home Screen"); v3Tracker.send(MapBuilder .createAppView() .build() );
- 移除對
GoogleAnalytics.setDebug()
的呼叫,並替換為GoogleAnalytics.getLogger().setLogLevel()
:// V2 (Old) GoogleAnalytics.getInstance(this).setDebug(true);
// V3 GoogleAnalytics.getInstance(this) .getLogger() .setLogLevel(LogLevel.VERBOSE); // VERBOSE | INFO | DEBUG | WARNING
進一步瞭解 Logger - 第 3 版 SDK 不會再在應用程式開啟時自動啟動新的工作階段 (除非使用 EasyTracker)。如要透過第 2 版自訂實作保留這項行為,您必須在使用者啟動應用程式時實作自己的工作階段控制邏輯:
- (選用) 在測試時設定
dryRun
標記,以免實際工作環境報表無法處理測試資料:
package com.example.app; import com.google.analytics.tracking.android.GoogleAnalytics; import com.google.analytics.tracking.android.Tracker; import android.app.Application; public class MyApp extends Application { private static Tracker mTracker; private static final String GA_PROPERTY_ID = "UA-XXXX-Y"; @Override public void onCreate() { super.onCreate(); mTracker = GoogleAnalytics.getInstance(this).getTracker(GA_PROPERTY_ID); // CAUTION: Setting session control directly on the tracker persists the // value across all subsequent hits, until it is manually set to null. // This should never be done in normal operation. // // mTracker.set(Fields.SESSION_CONTROL, "start"); // Instead, send a single hit with session control to start the new session. mTracker.send(MapBuilder .createEvent("UX", "appstart", null, null) .set(Fields.SESSION_CONTROL, "start") .build() ); } }
// When true, dryRun flag prevents data from being processed with reports. GoogleAnalytics.getInstance(this).setDryRun(true);
參考資料
以下各節提供如何使用 V3 SDK 設定和傳送資料的參考範例。
在第 3 版中 使用 Google 地圖傳送資料
在 V3 中,系統會使用單一 send()
方法傳送資料,該方法採用 Map
的 Google Analytics (分析) 欄位和值做為引數。提供 MapBuilder
公用程式類別,可簡化建立命中程序:
// Sending a screenview in v3 using MapBuilder. Tracker tracker = GoogleAnalytics.getInstance(this).getTracker("UA-XXXX-Y"); tracker.set(Fields.SCREEN_NAME, "Home Screen"); tracker.send(MapBuilder .createAppView() // Creates a Map of hit type 'AppView' (screenview). .set(Fields.customDimension(1), "Premium") // Set any additional fields for this hit. .build() // Build and return the Map to the send method. );
MapBuilder
類別可用來建構任何支援的命中類型,例如事件:
// Sending an event in v3 using MapBuilder.createEvent() tracker.send(MapBuilder .createEvent("UX", "touch", "menuButton", null) .build() );
在第 3 版中的追蹤器設定資料
您也可以使用 set()
方法,直接在 Tracker
上設定值。直接設定的值會套用至來自 Tracker
的所有後續命中:
// Values set directly on a tracker apply to all subsequent hits. tracker.set(Fields.SCREEN_NAME, "Home Screen"); // This screenview hit will include the screen name "Home Screen". tracker.send(MapBuilder.createAppView().build()); // And so will this event hit. tracker.send(MapBuilder .createEvent("UX", "touch", "menuButton", null) .build() );
如要清除在 Tracker
上設定的值,請將此屬性設為 null
:
// Clear the previously-set screen name value. tracker.set(Fields.SCREEN_NAME, null); // Now this event hit will not include a screen name value. tracker.send(MapBuilder .createEvent("UX", "touch", "menuButton", null) .build() );