Android 專用的 Google Analytics (分析) SDK：遷移至 v3

重要事項：本文件說明舊版 SDK。 新使用者應使用最新版的 SDK。

Google Analytics (分析) 新手應立即 開始使用第 3 版。

本指南說明如何升級至 Android 版 Google Analytics (分析) SDK 第 3 版。

資訊一覽：第 3 版的新功能

第 3 版中的 API 已重構，以便在原生和網路平台上更加一致。所有 V2 使用者都應留意下列變更：

• 現在，系統會使用單一 send(Map<String, String> parameters) 方法傳送命中資料。
• 偵錯模式已替換為 Logger
• EasyTracker 現已將 Tracker 設為子類別，導致介面出現一些變更。
• 新增： 新增了 dryRun 標記，以免報表中出現傳送的資料。

如需完整異動清單，請參閱「 Android 變更記錄」。

事前準備

開始升級至第 3 版之前，您必須準備下列項目：

• 已啟用通用 Analytics (分析) 的資源和應用程式設定檔
• Android 專用 Google Analytics (分析) SDK v3

升級路徑

如要開始使用，請從目前的實作項目中選取升級至 v3 的路徑：

• EasyTracker：v1.x 至 v3
• EasyTracker：v2.x 至 v3
• 自訂導入：v1.x 至 v3
• 自訂導入：v2.x 至 v3

EasyTracker：v1.x 至 v3

我們建議 EasyTracker v1.x 使用者按照第 3 版入門指南的說明，開始搭配 EasyTracker 使用第 3 版。

EasyTracker：v2.x 至 v3

2.x EasyTracker 版本使用者必須按照下列步驟操作，完成升級至第 3 版：

1. 將呼叫更新為 EasyTracker.getInstance() 以提供 Context:

   // v2 (Old)
   // EasyTracker.getInstance().activityStart(this);
   

   // v3:
   EasyTracker.getInstance(this).activityStart(this);
   

2. EasyTracker 現在將 Tracker 設為子類別 -- 移除對 EasyTracker.getTracker() 的呼叫：

   // v2 (Old)
   Tracker v2Tracker = EasyTracker.getInstance().getTracker();
   

   // v3
   Tracker v3Tracker = EasyTracker.getInstance(this);
   

3. 請將所有 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 版中傳送資料。



4. 將 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 參數參考資料。



5. 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();
   

   注意：在第 3 版中，SDK 不會保留應用程式層級的選擇不採用設定，因此每次執行應用程式時都必須設定。 進一步瞭解如何設定應用程式層級的選擇不採用功能
6. (選用) 在測試實作時，新增 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：

1. 將所有「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()
   );
   

2. 移除對 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. 第 3 版 SDK 不會再在應用程式開啟時自動啟動新的工作階段 (除非使用 EasyTracker)。如要透過第 2 版自訂實作保留這項行為，您必須在使用者啟動應用程式時實作自己的工作階段控制邏輯：

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

4. (選用) 在測試時設定 dryRun 標記，以免實際工作環境報表無法處理測試資料：

// 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 版傳送資料。

在第 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()
);

進一步瞭解如何在 v3 中設定資料