Android 版 Google Analytics(分析)SDK:迁移到 v3

本指南介绍了如何升级到 Android 版 Google Analytics(分析)SDK V3。

概览:V3 的新变化

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

  • 现在使用单个 send(Map<String, String> parameters) 方法发送命中。
  • 调试模式已替换为 Logger
  • EasyTracker 现在是 Tracker 的子类,会导致接口发生一些变化。
  • 新功能:添加了 dryRun 标志,以防止所发送的数据出现在报告中。

如需完整的变更列表,请参阅 Android 变更日志

准备工作

在开始升级到 v3 之前,您需要有:

升级路径

要开始升级,请选择从您当前的实现方案到 v3 的升级路径:

EasyTracker:v1.x 到 v3

建议 EasyTracker v1.x 用户按照 v3 入门指南中的说明开始使用 Easy3 与 EasyTracker。

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 和以下某个详细程度值:verboseinfowarningerror
    <!-- 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();
    
  6. (可选)在测试实现时添加 ga_dryRun EasyTracker 参数并将其设置为 true,以防止测试数据显示在生产报告中:
  7. <!-- 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) 方法:
    // 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 自定义实现中保留此行为,则需要在用户启动应用时实现自己的会话控制逻辑:
  4. 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()
        );
      }
    }
    
    
  5. (可选)在测试过程中设置 dryRun 标志,以防止测试报告使用正式版报告进行处理:
  6. // 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 中设置数据