Android 版 Google Analytics（分析）SDK：迁移到 v3

重要提示：本文档介绍的是旧版 SDK。 新用户应使用最新版 SDK。

刚开始使用 Google Analytics（分析）的开发者应立即 开始使用 v3。

本指南将介绍如何升级到 Android 版 Google Analytics（分析）SDK V3。

概览：V3 的新变化

V3 中的 API 经过了重构，在本机平台和网络平台中更加一致。V2 用户应当注意以下变化：

• 命中现在使用单一 send(Map<String, String> parameters) 方法发送。
• 调试模式已替换为 Logger
• EasyTracker 现在是 Tracker 的子类，会导致对接口进行一些更改。
• 新功能 ：添加了 dryRun 标记，防止分派的数据显示在报告中。

如需查看完整的变更列表，请参阅 Android 更新日志。

准备工作

在开始升级到 v3 之前，您需要有：

• 启用了 Universal 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 用户按照 v3 入门指南中的说明，搭配 EasyTracker 使用 v3。

EasyTracker：v2.x 到 v3

v2.x EasyTracker 用户应按照以下步骤完成到 v3 的升级：

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

   详细了解如何在 v3 中发送数据。



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

   注意：在 v3 中，应用级选择停用设置由 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 的 v1.x 用户应遵循 V3 入门指南，并根据需要查阅高级配置开发者指南。

自定义实现：v2.x 到 v3

不使用 EasyTracker 的 v2.x 用户应按照以下步骤完成到 v3 的升级：

1. 使用新的 send(Map<String, String> parameters) 方法替换所有“send<hit-type>”便捷方法：

   // 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. v3 SDK 不再在应用打开时自动启动新会话（使用 EasyTracker 时除外）。如果希望保留 v2 自定义实现中的此行为，则需要在用户启动应用时实现您自己的会话控制逻辑：

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 来设置和发送数据。

在 v3 中使用地图发送数据

在 V3 中，数据的发送只使用一个 send() 方法，该方法接受包含 Google Analytics（分析）字段和值的 Map 作为参数。 我们提供了一个 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()
);

详细了解如何在 v3 中发送数据。

在跟踪器中设置数据 (v3)

您也可以使用 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 中设置数据