Расширенная конфигурация – Android SDK

В этом документе представлен обзор некоторых расширенных функций настройки Google Analytics SDK для Android v3.

Обзор

Google Analytics SDK для Android предоставляет класс Tracker для установки и отправки данных в Google Analytics, а также одноэлементный элемент GoogleAnalytics , который служит интерфейсом для глобальных значений конфигурации вашей реализации.

Инициализация

Прежде чем какие-либо данные можно будет измерить, вы должны инициализировать хотя бы один трекер через синглтон GoogleAnalytics , указав Context и идентификатор свойства Google Analytics:

// Initialize a tracker using a Google Analytics property ID.
GoogleAnalytics.getInstance(this).getTracker("UA-XXXX-Y")

Теперь этот трекер можно использовать для настройки и отправки данных в Google Analytics.

Настройка и отправка данных

Данные отправляются в Google Analytics путем установки карт пар параметр-значение на трекере и отправки их через методы set и send :

/*
 * Send a screen view to Google Analytics by setting a map of parameter
 * values on the tracker and calling send.
 */
Tracker tracker = GoogleAnalytics.getInstance(this).getTracker("UA-XXXX-Y");

HashMap<String, String> hitParameters = new HashMap<String, String>();
hitParameters.put(Fields.HIT_TYPE, "appview");
hitParameters.put(Fields.SCREEN_NAME, "Home Screen");

tracker.send(hitParameters);

Класс MapBuilder упрощает процесс создания обращений и рекомендуется для большинства случаев использования. Здесь мы можем отправить тот же вид экрана с меньшим количеством строк кода:

// Sending the same screen view hit using MapBuilder.createAppView()
tracker.send(MapBuilder
  .createAppView()
  .set(Fields.SCREEN_NAME, "Home Screen")
  .build()
);

Синтаксис протокола измерения амперсанда

Значения также могут быть установлены для одного обращения, задав значение в Builder , или для всех последующих обращений, установив его в самом объекте отслеживания, используя синтаксис амперсанда протокола измерений:

// Setting the content description field on a single hit using ampersand syntax.
tracker.send(MapBuilder
  .createAppView()
  .set(Fields.SCREEN_NAME, "Home Screen")
  .build()
);

Полный список доступных параметров протокола измерений см. в Справочнике параметров протокола измерений .

Применение значений к множественным обращениям

Любые значения, установленные непосредственно на трекере, будут сохранены и применены к нескольким обращениям, как в этом примере:

// Set screen name on the tracker to be sent with all hits.
tracker.set(Fields.SCREEN_NAME, "Home Screen");

// Send a screen view for "Home Screen"
tracker.send(MapBuilder
    .createAppView()
    .build()
);

// This event will also be sent with &cd=Home%20Screen.
tracker.send(MapBuilder
    .createEvent("UX", "touch", "menuButton", null)
    .build()
);

// Clear the screen name field when we're done.
tracker.set(Fields.SCREEN_NAME, null);

Непосредственно на трекере следует задавать только те значения, которые вы хотите сохранить при нескольких обращениях. Установка имени экрана на трекере имеет смысл, поскольку одно и то же значение может применяться к последующим просмотрам экрана и обращениям к событиям. Однако не рекомендуется задавать на трекере такое поле, как тип попадания, поскольку оно, скорее всего, будет меняться при каждом попадании.

Использование нескольких трекеров

В одной реализации можно использовать несколько трекеров, что может быть полезно для отправки данных нескольким свойствам:

Tracker t1 = GoogleAnalytics.getInstance(this).getTracker("UA-XXXX-1");

// Trackers may be named. By default, name is set to the property ID.
Tracker t2 = GoogleAnalytics.getInstance(this).getTracker("altTracker", "UA-XXXX-2";

t1.set(Fields.SCREEN_NAME, "Home Screen");
t2.set(Fields.SCREEN_NAME, getClass().toString());

// Send screen view to UA-XXXX-1.
t1.send(MapBuilder
   .createAppView()
   .build()
);

// Send screen view to UA-XXXX-2.
t2.send(MapBuilder
   .createAppView()
   .build()
);

Функции автоматического измерения, такие как автоматический экран и измерение неперехваченных исключений, будут использовать только один трекер для отправки данных в Google Analytics. Если вы используете эти функции и хотите отправлять данные с помощью других трекеров, вам придется сделать это вручную.

Использование трекера по умолчанию

Google Analytics поддерживает трекер по умолчанию. Первый инициализированный трекер становится трекером по умолчанию, но его можно переопределить:

// Tracker t1 becomes the default tracker because it is initialized first.
Tracker t1 = GoogleAnalytics.getInstance(this).getTracker("UA-XXXX-1");
Tracker t2 = GoogleAnalytics.getInstance(this).getTracker("UA-XXXX-2");


// Returns tracker t1.
Tracker defaultTracker = GoogleAnalytics.getInstance(this).getDefaultTracker();

// Hit sent to UA-XXXX-1.
defaultTracker.send(MapBuilder
    .createAppView()
    .set(Fields.SCREEN_NAME, "Home Screen")
    .build()
);

// Override the default tracker.
GoogleAnalytics.getInstance(this).setDefaultTracker(t2);

// Now this call returns tracker t2.
defaultTracker = GoogleAnalytics.getInstance(this).getDefaultTracker();

// Hit sent to UA-XXXX-2.
defaultTracker.send(MapBuilder
    .createAppView()
    .set(Fields.SCREEN_NAME, getClass().toString())
    .build()
);

Выборка

Вы можете включить выборку на стороне клиента, чтобы ограничить количество обращений, отправляемых в Google Analytics. Если ваше приложение имеет большое количество пользователей или иным образом отправляет большой объем данных в Google Analytics, включение выборки поможет обеспечить бесперебойную отчетность.

Например, чтобы включить выборку на стороне клиента с частотой 50 % с помощью EasyTracker и XML, используйте следующий параметр в файле analytics.xml :

<string name="ga_sampleFrequency">50.0</string>

Чтобы программно включить выборку на стороне клиента для трекера:

mTracker.set(Fields.SAMPLE_RATE, 50.0d);

Отказ на уровне приложения

Вы можете включить флаг отказа на уровне приложения, который отключит Google Analytics во всем приложении. Обратите внимание, что этот флаг должен устанавливаться каждый раз при запуске приложения, и по умолчанию он имеет значение NO .

Чтобы получить настройку отказа на уровне приложения, используйте:

boolean isOptedOut = GoogleAnalytics.getInstance(this).getAppOptOut();

Чтобы настроить отказ на уровне приложения, используйте:

GoogleAnalytics.getInstance(this).setAppOptOut(true);

В типичной реализации приложение может прослушивать изменения в SharedPreferences и соответствующим образом обновлять настройку отказа от Google Analytics:

SharedPreferences userPrefs = PreferenceManager.getDefaultSharedPreferences(this);

userPrefs.registerOnSharedPreferenceChangeListener(new SharedPreferences.OnSharedPreferenceChangeListener () {

  @Override
  public void onSharedPreferenceChanged(SharedPreferences sharedPreferences,
      String key) {

    if (key.equals(TRACKING_PREF_KEY)) {
      GoogleAnalytics.getInstance(getApplicationContext()).setAppOptOut(sharedPreferences.getBoolean(key, false));
    } else {
    // Any additional changed preference handling.
    }
  }
});

Тестирование и отладка

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

Пробный прогон

SDK предоставляет флаг dryRun , который, если он установлен, предотвращает отправку любых данных в Google Analytics. Флаг dryRun следует устанавливать каждый раз, когда вы тестируете или отлаживаете реализацию и не хотите, чтобы тестовые данные появлялись в ваших отчетах Google Analytics.

Чтобы установить флаг пробного запуска:

// When dry run is set, hits will not be dispatched, but will still be logged as
// though they were dispatched.
GoogleAnalytics.getInstance(this).setDryRun(true);

Регистратор

Интерфейс Logger предназначен для обработки полезных сообщений из SDK на следующих уровнях детализации: error , warning , info и verbose .

SDK инициализирует стандартную реализацию Logger , которая по умолчанию записывает на консоль только сообщения о предупреждениях или ошибках. Эти сообщения будут доступны в logcat. Чтобы установить уровень детализации Logger :

// Set the log level to verbose.
GoogleAnalytics.getInstance(this).getLogger()
    .setLogLevel(LogLevel.VERBOSE);

Также можно использовать пользовательские реализации Logger :

// Provide a custom logger.
GoogleAnalytics.getInstance(this).setLogger(new CustomLogger ());

Полный пример

В приведенном ниже примере показан код, необходимый для инициализации реализации Google Analytics и отправки изображения одного экрана.

package com.example.app;

import com.google.analytics.tracking.android.GAServiceManager;
import com.google.analytics.tracking.android.GoogleAnalytics;
import com.google.analytics.tracking.android.Tracker;

import android.app.Application;
import android.content.SharedPreferences;
import android.preference.PreferenceManager;


/*
 * An advanced Google Analytics implementation may be initialized
 * in a subclass of Application. Note that this example assumes data
 * only needs to be sent to a single Google Analytics property ID.
 */
public class MyApp extends Application {

  private static GoogleAnalytics mGa;
  private static Tracker mTracker;

  /*
   * Google Analytics configuration values.
   */
  // Placeholder property ID.
  private static final String GA_PROPERTY_ID = "UA-XXXX-Y";

  // Dispatch period in seconds.
  private static final int GA_DISPATCH_PERIOD = 30;

  // Prevent hits from being sent to reports, i.e. during testing.
  private static final boolean GA_IS_DRY_RUN = false;

  // GA Logger verbosity.
  private static final LogLevel GA_LOG_VERBOSITY = LogLevel.INFO;

  // Key used to store a user's tracking preferences in SharedPreferences.
  private static final String TRACKING_PREF_KEY = "trackingPreference";


  /*
   * Method to handle basic Google Analytics initialization. This call will not
   * block as all Google Analytics work occurs off the main thread.
   */
  private void initializeGa() {
    mGa = GoogleAnalytics.getInstance(this);
    mTracker = mGa.getTracker(GA_PROPERTY_ID);

    // Set dispatch period.
    GAServiceManager.getInstance().setLocalDispatchPeriod(GA_DISPATCH_PERIOD);

    // Set dryRun flag.
    mGa.setDryRun(GA_IS_DRY_RUN);

    // Set Logger verbosity.
    mGa.getLogger().setLogLevel(GA_LOG_VERBOSITY);

    // Set the opt out flag when user updates a tracking preference.
    SharedPreferences userPrefs = PreferenceManager.getDefaultSharedPreferences(this);
    userPrefs.registerOnSharedPreferenceChangeListener(new SharedPreferences.OnSharedPreferenceChangeListener () {
      @Override
      public void onSharedPreferenceChanged(SharedPreferences sharedPreferences,
          String key) {
        if (key.equals(TRACKING_PREF_KEY)) {
          GoogleAnalytics.getInstance(getApplicationContext()).setAppOptOut(sharedPreferences.getBoolean(key, false));
        }
      }
    });
  }

  @Override
  public void onCreate() {
    super.onCreate();
    initializeGa();
  }

  /*
   * Returns the Google Analytics tracker.
   */
  public static Tracker getGaTracker() {
    return mTracker;
  }

  /*
   * Returns the Google Analytics instance.
   */
  public static GoogleAnalytics getGaInstance() {
    return mGa;
  }
}

Далее измеряется просмотр экрана, когда пользователю отображается первый экран:

package com.example.app

import android.app.Activity

/**
 * A simple Activity that sends a screen view to Google Analytics
 * when it is displayed to the user.
 */
public class HomeScreen extends Activity {

  private static final String SCREEN_LABEL = "Home Screen";

  @Override
  public void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);

    // Fields set on a tracker persist for all hits, until they are
    // overridden or cleared by assignment to null.
    MyApp.getGaTracker().set(Fields.SCREEN_NAME, SCREEN_LABEL);
  }

  @Override
  public void onStart() {
    super.onStart();

    // Send a screen view when the Activity is displayed to the user.
    MyApp.getGaTracker().send(MapBuilder
        .createAppView.build());
  }
}