Configuração avançada – SDK para Android

Este documento contém 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 uma interface para os valores de configuração globais da sua implementação.

Inicialização

Para que os dados sejam avaliados, 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, você precisa definir mapas de pares de valores de parâmetros no rastreador e enviá-los pelos 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 criar 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 ao definir o valor em um Builder ou em todos os hits subsequentes ao defini-los no próprio objeto do rastreador por meio da sintaxe do "e" comercial do Protocolo de avaliação:

// 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 ativar a amostragem do lado do cliente a uma taxa de 50% pelo EasyTracker e 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

É possível ativar uma sinalização de desativação no nível do aplicativo que desativa o Google Analytics em todo o aplicativo. Essa sinalização precisa ser definida sempre que o aplicativo é iniciado e o padrão é 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 conforme necessário:

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 tem uma sinalização dryRun que, quando definida, impede que dados sejam enviados ao Google Analytics. A sinalização dryRun precisa ser definida sempre que você estiver testando ou depurando uma implementação e não quiser 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 de Logger, faça o seguinte:

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

Implementações personalizadas de Logger também podem ser usadas:

// 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 é mostrada ao 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());
  }
}