Configuração avançada: SDK do Android

Este documento apresenta uma visão geral de alguns dos recursos de configuração avançada do SDK do Google Analytics para Android v3.

Visão geral

O SDK do Google Analytics para Android fornece uma classe Tracker para definir e enviar dados ao Google Analytics, e um Singleton GoogleAnalytics que serve como interface para os valores de configuração globais da sua implementação.

Inicialização

Antes de medir os dados, você precisa inicializar pelo menos um rastreador por meio do Singleton GoogleAnalytics fornecendo um Context e um ID da propriedade do Google Analytics:

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

Agora esse rastreador pode ser usado para definir e enviar dados ao Google Analytics.

Configuração e envio de dados

Para enviar dados ao Google Analytics, defina mapas de pares de valores de parâmetros no rastreador e envie-os por meio dos métodos set e 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);

A classe MapBuilder simplifica o processo de criação de hits e é recomendada para a maioria dos casos de uso. Com o comando a seguir, podemos enviar a mesma exibição de tela com menos linhas de código:

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

Sintaxe do "e" comercial do Protocolo de avaliação

Os valores também podem ser definidos em um único hit, definindo o valor em um Builder, ou em todos os hits subsequentes, definindo-o no próprio objeto do rastreador, usando a sintaxe do"e"comercial do Measurement Protocol:

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

Para ver a lista completa dos parâmetros do Protocolo de avaliação disponíveis, consulte a Referência de parâmetros do Protocolo de avaliação.

Aplicação de valores a vários hits

Todos os valores definidos diretamente no rastreador serão persistidos e aplicados a vários hits, como neste exemplo:

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

Somente os valores que você deseja persistir em vários hits devem ser definidos diretamente no rastreador. Convém definir um nome de tela em um rastreador, pois o mesmo valor pode ser aplicado a hits subsequentes de exibições de tela e eventos. No entanto, não é recomendado definir um campo como o tipo de hit no rastreador, pois ele provavelmente mudará a cada hit.

Uso de vários rastreadores

Vários rastreadores podem ser usados em uma única implementação, o que pode ser útil para enviar dados a várias propriedades:

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

Recursos de avaliação automatizados, como a avaliação automática de telas e exceções não identificadas, usam somente um rastreador para enviar dados ao Google Analytics. Se você usa esses recursos e quer enviar dados por meio de outros rastreadores, precisa fazer isso manualmente.

Uso do rastreador padrão

O Google Analytics mantém um rastreador padrão. O primeiro rastreador inicializado se torna o rastreador padrão, mas é possível substituí-lo:

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

Amostragem

Você pode ativar a amostragem do cliente para limitar o número de hits enviados ao Google Analytics. Se seu aplicativo tem um número grande de usuários ou envia um grande volume de dados ao Google Analytics, ativar a amostragem ajuda a garantir relatórios ininterruptos.

Por exemplo, para permitir a amostragem do lado do cliente a uma taxa de 50% por meio do EasyTracker e do XML, use o seguinte parâmetro no arquivo analytics.xml:

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

Para ativar a amostragem do cliente de modo programático para um rastreador:

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

Desativação no nível do aplicativo

Você pode ativar uma sinalização de desativação no nível do aplicativo que desativará o Google Analytics em todo o aplicativo. Essa sinalização precisa ser definida sempre que o aplicativo for iniciado e o padrão será NO.

Para acessar a configuração de desativação no nível do aplicativo, use:

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

Para definir a desativação no nível do aplicativo, use:

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

Em uma implementação típica, um app pode detectar uma mudança em SharedPreferences e atualizar a configuração de desativação do Google Analytics de acordo com isso:

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

Como testar e depurar

O SDK do Google Analytics para Android fornece ferramentas para facilitar os testes e a depuração.

Dry Run

O SDK fornece uma sinalização dryRun que, quando definida, impede que qualquer dado seja enviado ao Google Analytics. A sinalização dryRun precisa ser definida sempre que você está testando ou depurando uma implementação e não quer que os dados de teste apareçam nos relatórios do Google Analytics.

Para definir a sinalização "dry run":

// 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

A interface Logger é fornecida para processar mensagens úteis do SDK nestes níveis de verbosidade: error, warning, info e verbose.

O SDK inicializa uma implementação Logger padrão, que, por padrão, só registra mensagens de aviso ou erro no console. Essas mensagens ficam disponíveis no logcat. Para definir o nível de detalhes do Logger:

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

Também é possível usar implementações personalizadas de Logger:

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

Exemplo completo

O exemplo abaixo mostra o código exigido para inicializar uma implementação do Google Analytics e enviar uma única exibição de tela.

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

Em seguida, uma exibição de tela é medida quando a primeira tela é exibida para um usuário:

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