Configurazione avanzata

Questo documento fornisce una panoramica di alcune delle funzionalità di configurazione avanzate dell'SDK di Google Analytics v4 per Android.

Panoramica

L'SDK Google Analytics v4 per Android fornisce una classe Tracker per impostare e inviare dati a Google Analytics e un singleton GoogleAnalytics che funge da interfaccia per i valori di configurazione globali dell'implementazione.

Inizializzazione

Prima di poter misurare i dati, devi inizializzare almeno un tracker tramite il singleton GoogleAnalytics fornendo un oggetto Context e un ID proprietà di Google Analytics. Per maggiori dettagli, consulta la documentazione di riferimento di Google Analytics.

Utilizzo di un file di configurazione

È anche possibile inizializzare un tracker utilizzando un file di configurazione. Ad esempio:

package com.google.android.apps.mobileplayground;

import android.app.Application;
import com.google.android.gms.analytics.GoogleAnalytics;
import com.google.android.gms.analytics.Tracker;
import java.util.HashMap;

/**
 * An extension to Application class to provide tracker for analytics purposes. Having the tracker
 * instances here allows all the activities to access the same tracker instances. The trackers can
 * be initialised on startup or when they are required based on performance requirements.
 */
public class AnalyticsSampleApp extends Application {

  // The following line should be changed to include the correct property id.
  private static final String PROPERTY_ID = "UA-XXXXX-Y";

  /**
   * Enum used to identify the tracker that needs to be used for tracking.
   *
   * A single tracker is usually enough for most purposes. In case you do need multiple trackers,
   * storing them all in Application object helps ensure that they are created only once per
   * application instance.
   */
  public enum TrackerName {
    APP_TRACKER, // Tracker used only in this app.
    GLOBAL_TRACKER, // Tracker used by all the apps from a company. eg: roll-up tracking.
    ECOMMERCE_TRACKER, // Tracker used by all ecommerce transactions from a company.
  }

  HashMap<TrackerName, Tracker> mTrackers = new HashMap<TrackerName, Tracker>();

  public AnalyticsSampleApp() {
    super();
  }
  synchronized Tracker getTracker(TrackerName trackerId) {
    if (!mTrackers.containsKey(trackerId)) {

      GoogleAnalytics analytics = GoogleAnalytics.getInstance(this);
      Tracker t = (trackerId == TrackerName.APP_TRACKER) ? analytics.newTracker(PROPERTY_ID)
          : (trackerId == TrackerName.GLOBAL_TRACKER) ? analytics.newTracker(R.xml.global_tracker)
              : analytics.newTracker(R.xml.ecommerce_tracker);
      mTrackers.put(trackerId, t);

    }
    return mTrackers.get(trackerId);
  }
}

Impostazione e invio di dati

I dati vengono inviati a Google Analytics utilizzando i generatori per impostare le coppie parametro-valore inviandoli tramite il metodo send del tracker.

L'esempio seguente mostra come inviare una visualizzazione di schermata a Google Analytics creando una vista dell'app e chiamando il metodo di invio del tracker:

// Get tracker.
Tracker t = ((AnalyticsSampleApp) getActivity().getApplication()).getTracker(
    TrackerName.APP_TRACKER);

// Set screen name.
t.setScreenName(screenName);

// Send a screen view.
t.send(new HitBuilders.ScreenViewBuilder().build());

Sintassi e commerciale di Measurement Protocol

Puoi utilizzare la sintassi e commerciale di Measurement Protocol per impostare i valori di un singolo hit con un elemento HitBuilders.ScreenViewBuilder. Per impostare i valori per tutti gli hit successivi, utilizza l'oggetto tracker stesso.

// Setting the content description field on a single hit using ampersand syntax.
tracker.send(new HitBuilders.ScreenViewBuilder()
  .set("&cd", "Home Screen")
  .build()
);

Per l'elenco completo dei parametri di Measurement Protocol disponibili, consulta il documento di riferimento per i parametri di Measurement Protocol.

Applicazione di valori a più hit

Qualsiasi valore impostato direttamente sul tracker verrà mantenuto e applicato a più hit, come in questo esempio:

// Get tracker.
Tracker t = ((AnalyticsSampleApp) getActivity().getApplication()).getTracker(
    TrackerName.APP_TRACKER);

// Set screen name.
t.setScreenName(screenName);

// Send a screen view.
t.send(new HitBuilders.ScreenViewBuilder().build());

// This event will also be sent with the most recently set screen name.
// Build and send an Event.
t.send(new HitBuilders.EventBuilder()
    .setCategory(getString(categoryId))
    .setAction(getString(actionId))
    .setLabel(getString(labelId))
    .build());

// Clear the screen name field when we're done.
t.setScreenName(null);

Solo i valori che vuoi mantenere per più hit devono essere impostati direttamente nel tracker. L'impostazione di un nome di schermata su un tracker avrebbe senso, poiché lo stesso valore può essere applicato a visualizzazioni di schermata e hit da evento successivi. Tuttavia, non è consigliabile impostare un campo come il tipo di hit sul tracker, perché probabilmente cambierà a ogni hit.

Utilizzo di più tracker

Nella tua applicazione mobile, puoi utilizzare più tracker per inviare dati a proprietà diverse:

public class MyApp extends Application {

  public void initTrackers() {
    GoogleAnalytics analytics = GoogleAnalytics.getInstance(this);

    globalTracker = analytics.newTracker(R.xml.global_tracker);
    ecommerceTracker = analytics.newTracker(R.xml.ecommerce_tracker);
  }

  public static Tracker globalTracker;
  public static Tracker ecommerceTracker;

  ...
}

Sebbene la tua applicazione mobile possa disporre di più tracker, puoi utilizzare un solo tracker per segnalare le eccezioni non rilevate chiamando il metodo enableExceptionReporting() sul tracker.

Campionamento

Puoi attivare il campionamento lato client per limitare il numero di hit inviati a Google Analytics. Se la tua app ha un numero elevato di utenti o invia un elevato volume di dati a Google Analytics, l'attivazione del campionamento aiuta a garantire report senza interruzioni.

Ad esempio, per abilitare il campionamento lato client a una frequenza del 50%, utilizza il seguente parametro nel file di configurazione:

<string name="ga_sampleFrequency">50.0</string>

Per abilitare il campionamento lato client in modo programmatico per un tracker:

mTracker.setSampleRate(50.0d);

Per evitare incoerenze nei report, ciascuna vista (profili) delle app deve contenere dati raccolti con la stessa frequenza di campionamento. Se versioni diverse della tua app utilizzano frequenze di campionamento diverse, dovrai configurare i filtri della vista (profilo) utilizzando la dimensione della versione dell'app per mantenere separati i dati di ogni versione dell'app.

Disattivazione a livello di app

Puoi abilitare un flag di disattivazione a livello di app che disattiverà Google Analytics nell'intera app. Tieni presente che questo flag deve essere impostato a ogni avvio dell'app e che, per impostazione predefinita, sarà false.

Per attivare l'impostazione di disattivazione a livello di app, utilizza:

boolean isOptedOut = GoogleAnalytics.getInstance(this).getAppOptOut();

Per impostare la disattivazione a livello di app, utilizza:

GoogleAnalytics.getInstance(this).setAppOptOut(true);

In un'implementazione tipica, un'app potrebbe rimanere in ascolto di una modifica in SharedPreferences e aggiornare di conseguenza l'impostazione di disattivazione di Google Analytics:

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

Eliminare i dati utente lato client

Se devi reimpostare o eliminare i dati lato client di Google Analytics per i tuoi utenti finali, puoi eliminare il file ID client.

L'eliminazione del file gaClientId impone la generazione di un nuovo ID client, mentre tutti gli hit successivi utilizzeranno il nuovo ID client. I dati precedenti non verranno associati al nuovo ID client.

Per eliminare il file gaClientId, utilizza il metodo Context.deleteFile:

context.deleteFile("gaClientId");

Anonimizza IP

L'attivazione della funzionalità di anonimizzazione IP indica a Google Analytics di anonimizzare le informazioni IP inviate dall'SDK rimuovendo l'ultimo ottetto dell'indirizzo IP prima di archiviarlo.

Per abilitare la funzionalità di anonimizzazione IP, utilizza il seguente parametro nel file di configurazione:

<string name="ga_anonymizeIp">true</string>

Per abilitare in modo programmatico la funzionalità IP per un tracker, utilizza il metodo setAnonymizeIp:

mTracker.setAnonymizeIp(true)

Il metodo setAnonymizeIp può essere chiamato in qualsiasi momento.

Test e debug

La versione 4 dell'SDK di Google Analytics per Android fornisce strumenti che semplificano i test e il debug.

Prova

L'SDK fornisce un flag dryRun che, se impostato, impedisce l'invio di dati a Google Analytics. Il flag dryRun deve essere impostato ogni volta che esegui il test o il debug di un'implementazione e non vuoi che i dati dei test vengano visualizzati nei report di Google Analytics.

Per impostare il flag di prova:

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

Google Analytics accederà a logcat nel tag GAv4 utilizzando il sistema Android Log. Per impostazione predefinita, sono abilitati solo i livelli ERROR, WARN e INFO. Per attivare il livello DEBUG, esegui il seguente comando adb sul tuo dispositivo o emulatore:

adb shell setprop log.tag.GAv4 DEBUG

Per visualizzare solo i messaggi di Google Analytics da logcat, utilizza il seguente comando:

adb logcat -v time -s GAv4

Per ulteriori informazioni, consulta la pagina Riferimento Logger Google Analytics.