Questa guida descrive come eseguire l'upgrade alla versione V3 dell'SDK Google Analytics per Android.
Riepilogo: novità della V3
Le API nella V3 sono state sottoposte a refactoring per garantire una maggiore coerenza tra le piattaforme native e web. Tutti gli utenti della versione 2 devono notare i seguenti cambiamenti:
- Ora gli hit vengono inviati con un unico metodo
send(Map<String, String> parameters)
. - La modalità di debug è stata sostituita con
Logger
- EasyTracker ora sottoclasse
Tracker
, con alcune modifiche all'interfaccia. - Novità: è stato aggiunto un flag
dryRun
per impedire la visualizzazione dei dati inviati nei report.
Per l'elenco completo delle modifiche, consulta il log delle modifiche di Android.
Prima di iniziare
Prima di iniziare l'upgrade alla versione 3, è necessario quanto segue:
- Una proprietà abilitata per Universal Analytics e un profilo dell'app
- SDK di Google Analytics per Android v3
Percorsi di upgrade
Per iniziare, seleziona un percorso di upgrade alla versione 3 dall'implementazione attuale:
- EasyTracker: da v1.x a v3
- FacileTracker: da v2.x a v3
- Implementazione personalizzata: dalla versione 1.x alla versione 3
- Implementazione personalizzata: dalla versione 2.x alla v3
EasyTracker: da v1.x a v3
È consigliabile che gli utenti di EasyTracker v1.x seguano la Guida introduttiva v3 per iniziare a utilizzare la versione 3 con EasyTracker.
EasyTracker: da v2.x a v3
Gli utenti della versione 2.x di EasyTracker devono seguire questi passaggi per completare l'upgrade alla versione 3:
- Aggiorna le chiamate a
EasyTracker.getInstance()
per fornireContext:
// v2 (Old) // EasyTracker.getInstance().activityStart(this);
// v3: EasyTracker.getInstance(this).activityStart(this);
EasyTracker
ora sottoclassiTracker
-- rimuovi le chiamate aEasyTracker.getTracker()
:// v2 (Old) Tracker v2Tracker = EasyTracker.getInstance().getTracker();
// v3 Tracker v3Tracker = EasyTracker.getInstance(this);
- Sostituisci tutti i metodi di convenienza
send<hit-type>
con il nuovo metodosend(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() );
Scopri di più sull'invio di dati in v3. - Sostituisci il parametro
ga_debug
di EasyTracker conga_logLevel
e uno di questi valori di livello di dettaglio: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>
Consulta la pagina Riferimento ai parametri di EasyTracker per ulteriori dettagli. - L'elemento
GoogleAnalytics.requestAppOptOut()
è deprecato, usa inveceGoogleAnalytics.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();
- (Facoltativo) Aggiungi il parametro
ga_dryRun
EasyTracker e impostato sutrue
durante il test dell'implementazione per evitare che i dati dei test vengano visualizzati nei report di produzione:
<!-- 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>
Implementazione personalizzata: dalla versione 1.x alla versione 3
Gli utenti della versione 1.x che non utilizzano EasyTracker
devono seguire la
Guida introduttiva V3 e consultare la
Guida per gli sviluppatori
sulla configurazione avanzata, se necessario.
Implementazione personalizzata: dalla versione 2.x alla v3
Gli utenti della versione 2.x che non utilizzano EasyTracker
devono seguire i passaggi riportati di seguito per completare l'upgrade alla versione 3:
- Sostituisci tutti i metodi di convenienza "send<hit-type>" con il nuovo
metodo
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() );
- Rimuovi le chiamate a
GoogleAnalytics.setDebug()
, sostituisci conGoogleAnalytics.getLogger().setLogLevel()
:// V2 (Old) GoogleAnalytics.getInstance(this).setDebug(true);
// V3 GoogleAnalytics.getInstance(this) .getLogger() .setLogLevel(LogLevel.VERBOSE); // VERBOSE | INFO | DEBUG | WARNING
Scopri di più su Logger - L'SDK v3 non avvia più automaticamente una nuova sessione all'apertura dell'app, tranne quando utilizzi EasyTracker. Se vuoi mantenere questo comportamento da un'implementazione personalizzata v2, devi implementare la tua logica di controllo della sessione quando un utente avvia l'app:
- (Facoltativo) Imposta il flag
dryRun
durante i test per impedire l'elaborazione dei dati di test con i report di produzione:
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);
Riferimento
Le seguenti sezioni forniscono esempi di riferimento su come impostare e inviare dati utilizzando l'SDK V3.
Invio di dati utilizzando Maps in v3
Nella versione V3, i dati vengono inviati utilizzando un singolo metodo send()
che prende come argomento un Map
di campi e valori di Google Analytics. Viene fornita una classe di utilità MapBuilder
per semplificare il processo di creazione degli hit:
// 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. );
La classe MapBuilder
può essere utilizzata per creare qualsiasi tipo di hit supportato, come gli eventi:
// Sending an event in v3 using MapBuilder.createEvent() tracker.send(MapBuilder .createEvent("UX", "touch", "menuButton", null) .build() );
Scopri di più sull'invio di dati nella versione 3.
Impostazione dei dati sul tracker in v3
I valori possono anche essere impostati direttamente su un elemento Tracker
utilizzando il metodo set()
.
I valori impostati direttamente vengono applicati a tutti gli hit successivi da quello
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() );
Per cancellare un valore impostato in Tracker
, imposta la proprietà su 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() );