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:
- Atualize as chamadas para
EasyTracker.getInstance()
para fornecer umContext:
// v2 (Old) // EasyTracker.getInstance().activityStart(this);
// v3: EasyTracker.getInstance(this).activityStart(this);
EasyTracker
agora é uma subclasse deTracker
: remova chamadas paraEasyTracker.getTracker()
:// v2 (Old) Tracker v2Tracker = EasyTracker.getInstance().getTracker();
// v3 Tracker v3Tracker = EasyTracker.getInstance(this);
- Substitua todos os métodos de conveniência
send<hit-type>
pelo novo métodosend(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. - Substitua o parâmetro
ga_debug
do EasyTracker porga_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. - O uso de
GoogleAnalytics.requestAppOptOut()
foi descontinuado. UseGoogleAnalytics.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();
- (Opcional) Adicione o parâmetro
ga_dryRun
do EasyTracker e defina-o comotrue
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:
- 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() );
- Remova chamadas para
GoogleAnalytics.setDebug()
e substitua porGoogleAnalytics.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 - 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:
- (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:
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() ); } }
// 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() );