Google Analytics SDK для Android: переход на версию 3

В этом руководстве описывается, как перейти на версию 3 Google Analytics SDK для Android.

Краткий обзор: что нового в версии 3

API в версии 3 были переработаны, чтобы обеспечить большую согласованность на собственных и веб-платформах. Всем пользователям V2 следует обратить внимание на эти изменения:

  • Обращения теперь отправляются с использованием одного метода send(Map<String, String> parameters) .
  • Режим отладки заменен на Logger
  • EasyTracker теперь является подклассом Tracker , что приводит к некоторым изменениям в интерфейсе.
  • Новое: добавлен флаг dryRun , предотвращающий появление отправленных данных в отчетах.

Полный список изменений можно найти в журнале изменений Android .

Прежде чем вы начнете

Прежде чем начать обновление до версии 3, вам потребуется следующее:

Пути обновления

Чтобы начать, выберите путь обновления до v3 из вашей текущей реализации:

EasyTracker: от версии 1.x до версии 3

Пользователям EasyTracker v1.x рекомендуется следовать Руководству по началу работы с версией 3, чтобы начать использовать версию 3 с EasyTracker.

EasyTracker: от версии 2.x до версии 3

Пользователи EasyTracker v2.x должны выполнить следующие действия для завершения обновления до 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()
);
    Узнайте больше об отправке данных в версии 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();
  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

Пользователи версии 1.x, которые не используют EasyTracker должны следовать Руководству по началу работы с версией 3 и при необходимости обращаться к Руководству разработчика расширенной конфигурации .

Пользовательская реализация: от v2.x до v3

Пользователи версии 2.x, которые не используют EasyTracker должны выполнить следующие действия, чтобы завершить обновление до версии 3:

  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. SDK v3 больше не запускает автоматически новый сеанс при открытии приложения (кроме случаев использования EasyTracker). Если вы хотите сохранить это поведение в пользовательской реализации версии 2, вам необходимо реализовать собственную логику управления сеансом, когда пользователь запускает приложение:
    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()
    );
  }
}
  4. (Необязательно) Установите флаг dryRun во время тестирования, чтобы предотвратить обработку тестовых данных в ваших производственных отчетах:
    5. // When true, dryRun flag prevents data from being processed with reports.
GoogleAnalytics.getInstance(this).setDryRun(true);

Ссылка

В следующих разделах представлены справочные примеры установки и отправки данных с помощью V3 SDK.

Отправка данных с помощью карт в версии 3

В версии 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 .

Настройка данных на трекере в v3

Значения также можно устанавливать непосредственно на Tracker с помощью метода set() . Значения, установленные напрямую, применяются ко всем последующим обращениям из этого 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()
);

Узнайте больше о настройке данных в версии 3.