SDK do Google Analytics para Android: migração para a v3

Importante: este documento descreve uma versão legada do SDK. Novos usuários precisam usar o SDK mais recente.

Os desenvolvedores iniciantes no Google Analytics devem começar a usar a versão 3 agora mesmo.

Este guia descreve como fazer upgrade para a V3 do SDK do Google Analytics para Android.

Visão rápida: o que há de novo na V3

As APIs na V3 foram refatoradas para serem mais consistentes em plataformas nativas e da Web. Todos os usuários da V2 devem observar estas alterações:

• Os hits agora são enviados usando um único método send(Map<String, String> parameters).
• O modo de depuração foi substituído por uma Logger.
• O EasyTracker agora é uma subclasse da Tracker, resultando em algumas mudanças na interface
• Novo: uma sinalização dryRun foi adicionada para evitar que os dados enviados apareçam nos relatórios.

Para conferir a lista completa das mudanças, consulte o Registro de alterações do Android.

Antes de começar

Antes de começar a fazer upgrade para a v3, você precisará de:

• Uma propriedade ativada para o Universal Analytics e um perfil de aplicativo
• SDK do Google Analytics para Android v3

Caminhos de upgrade

Para começar, selecione um caminho de upgrade para a v3 a partir da sua implementação atual:

• EasyTracker: v1.x para v3
• EasyTracker: v2.x para v3
• Implementação personalizada: v1.x para v3
• Implementação personalizada: v2.x para v3

EasyTracker: v1.x para v3

É recomendável que os usuários do EasyTracker v1.x sigam o Guia de primeiros passos v3 para começar a usar a v3 com o EasyTracker.

EasyTracker: v2.x para v3

Os usuários do EasyTracker v2.x devem seguir estas etapas para concluir o upgrade para a v3:

1. Atualize as chamadas para EasyTracker.getInstance() para fornecer um Context:

   // v2 (Old)
   // EasyTracker.getInstance().activityStart(this);
   

   // v3:
   EasyTracker.getInstance(this).activityStart(this);
   

2. EasyTracker agora é uma subclasse de Tracker: remova chamadas para EasyTracker.getTracker():

   // v2 (Old)
   Tracker v2Tracker = EasyTracker.getInstance().getTracker();
   

   // v3
   Tracker v3Tracker = EasyTracker.getInstance(this);
   

3. Substitua todos os métodos de conveniência send<hit-type> pelo novo método 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()
   );
   

   Saiba mais sobre o envio de dados na v3.



4. Substitua o parâmetro ga_debug do EasyTracker por ga_logLevel e um destes valores de detalhes: 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>
   

   . Consulte a Referência de parâmetros do EasyTracker para mais detalhes.



5. O uso de GoogleAnalytics.requestAppOptOut() foi descontinuado. Use 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();
   

   Atenção: na v3, a configuração de desativação no nível do app não é mantida pelo SDK e precisa ser definida sempre que o app é executado. Saiba mais sobre como configurar a desativação no nível do aplicativo
6. (Opcional) Adicione o parâmetro ga_dryRun do EasyTracker e defina-o como true ao testar a implementação para evitar que os dados de teste apareçam nos relatórios de produção:

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

Implementação personalizada: v1.x para v3

Os usuários da v1.x que não usam EasyTracker precisam seguir o Guia para iniciantes da V3 e consultar o Guia do desenvolvedor de configuração avançada conforme necessário.

Implementação personalizada: v2.x para v3

Os usuários da v2.x que não usam EasyTracker precisam seguir as etapas abaixo para concluir o upgrade para a v3:

1. Substitua todos os métodos de conveniência 'send<hit-type>' pelo novo método 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. Remova chamadas para GoogleAnalytics.setDebug() e substitua por GoogleAnalytics.getLogger().setLogLevel():

   // V2 (Old)
   GoogleAnalytics.getInstance(this).setDebug(true);
   

   // V3
   GoogleAnalytics.getInstance(this)
       .getLogger()
       .setLogLevel(LogLevel.VERBOSE);  // VERBOSE | INFO | DEBUG | WARNING
   

   Saiba mais sobre o Logger


3. O SDK v3 não inicia mais uma nova sessão automaticamente quando o app é aberto (exceto ao usar o EasyTracker). Se você quiser preservar esse comportamento de uma implementação personalizada v2, precisará implementar sua própria lógica de controle de sessão quando um usuário iniciar o app:

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. (Opcional) Defina a sinalização dryRun durante o teste para evitar que os dados de teste sejam processados com os relatórios de produção:

// When true, dryRun flag prevents data from being processed with reports.
GoogleAnalytics.getInstance(this).setDryRun(true);

Referência

As seções a seguir fornecem exemplos de referências de como definir e enviar dados usando o SDK V3.

Enviar dados usando o Google Maps na v3

Na V3, os dados são enviados com um único método send() que usa um Map dos campos e valores do Google Analytics como argumento. Uma classe de utilitário MapBuilder é fornecida para simplificar o processo de criação de hits:

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

A classe MapBuilder pode ser usada para criar qualquer um dos tipos de hit compatíveis, como eventos:

// Sending an event in v3 using MapBuilder.createEvent()
tracker.send(MapBuilder
    .createEvent("UX", "touch", "menuButton", null)
    .build()
);

Saiba mais sobre o envio de dados na v3.

Definição de dados no rastreador na v3

Os valores também podem ser definidos diretamente em um Tracker usando o método set(). Os valores definidos diretamente são aplicados a todos os hits subsequentes desse 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()
);

Para limpar um valor que foi definido no Tracker, defina a propriedade como 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()
);

Saiba mais sobre a definição de dados na v3