SDK Google Analytics per Android: migrazione alla versione 3

Importante: questo documento descrive una versione precedente dell'SDK. I nuovi utenti devono utilizzare l'SDK più recente.

Gli sviluppatori che non hanno mai utilizzato Google Analytics devono Iniziare subito con la versione 3.

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:

1. Aggiorna le chiamate a EasyTracker.getInstance() per fornire Context:

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

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

2. EasyTracker ora sottoclassi Tracker -- rimuovi le chiamate a EasyTracker.getTracker():

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

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

3. Sostituisci tutti i metodi di convenienza send<hit-type> con il nuovo metodo 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()
   );
   

   Scopri di più sull'invio di dati in v3.



4. Sostituisci il parametro ga_debug di EasyTracker con ga_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.



5. L'elemento GoogleAnalytics.requestAppOptOut() è deprecato, usa invece 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();
   

   Attenzione: nella versione 3, l'impostazione di disattivazione a livello di app non è resa persistente dall'SDK e deve essere impostata ogni volta che l'app viene eseguita. Scopri di più sull'impostazione della disattivazione a livello di applicazione
6. (Facoltativo) Aggiungi il parametro ga_dryRun EasyTracker e impostato su true 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:

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

2. Rimuovi le chiamate a GoogleAnalytics.setDebug(), sostituisci con GoogleAnalytics.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


3. 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:

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. (Facoltativo) Imposta il flag dryRun durante i test per impedire l'elaborazione dei dati di test con i report di produzione:

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

Scopri di più sull'impostazione dei dati nella versione 3