Configurazione avanzata - SDK per Android

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

Panoramica

L'SDK Google Analytics 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 un singleton GoogleAnalytics fornendo un Context e un ID proprietà di Google Analytics:

// Initialize a tracker using a Google Analytics property ID.
GoogleAnalytics.getInstance(this).getTracker("UA-XXXX-Y")

Ora questo tracker può essere utilizzato per l'impostazione e l'invio di dati a Google Analytics.

Impostazione e invio di dati

I dati vengono inviati a Google Analytics impostando mappe di coppie parametro-valore sul tracker e inviandole tramite i metodi set e send:

/*
 * Send a screen view to Google Analytics by setting a map of parameter
 * values on the tracker and calling send.
 */
Tracker tracker = GoogleAnalytics.getInstance(this).getTracker("UA-XXXX-Y");

HashMap<String, String> hitParameters = new HashMap<String, String>();
hitParameters.put(Fields.HIT_TYPE, "appview");
hitParameters.put(Fields.SCREEN_NAME, "Home Screen");

tracker.send(hitParameters);

La classe MapBuilder semplifica il processo di creazione degli hit ed è consigliata per la maggior parte dei casi d'uso. Qui possiamo inviare la stessa visualizzazione di schermata con meno righe di codice:

// Sending the same screen view hit using MapBuilder.createAppView()
tracker.send(MapBuilder
  .createAppView()
  .set(Fields.SCREEN_NAME, "Home Screen")
  .build()
);

Sintassi e commerciale di Measurement Protocol

I valori possono anche essere impostati per un singolo hit, impostandoli su un Builder o su tutti gli hit successivi, impostandoli sull'oggetto tracker stesso tramite la sintassi e commerciale di Measurement Protocol:

// Setting the content description field on a single hit using ampersand syntax.
tracker.send(MapBuilder
  .createAppView()
  .set(Fields.SCREEN_NAME, "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:

// Set screen name on the tracker to be sent with all hits.
tracker.set(Fields.SCREEN_NAME, "Home Screen");

// Send a screen view for "Home Screen"
tracker.send(MapBuilder
    .createAppView()
    .build()
);

// This event will also be sent with &cd=Home%20Screen.
tracker.send(MapBuilder
    .createEvent("UX", "touch", "menuButton", null)
    .build()
);

// Clear the screen name field when we're done.
tracker.set(Fields.SCREEN_NAME, 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

È possibile utilizzare più tracker in un'unica implementazione, il che può essere utile per l'invio di dati a più proprietà:

Tracker t1 = GoogleAnalytics.getInstance(this).getTracker("UA-XXXX-1");

// Trackers may be named. By default, name is set to the property ID.
Tracker t2 = GoogleAnalytics.getInstance(this).getTracker("altTracker", "UA-XXXX-2";

t1.set(Fields.SCREEN_NAME, "Home Screen");
t2.set(Fields.SCREEN_NAME, getClass().toString());

// Send screen view to UA-XXXX-1.
t1.send(MapBuilder
   .createAppView()
   .build()
);

// Send screen view to UA-XXXX-2.
t2.send(MapBuilder
   .createAppView()
   .build()
);

Le funzionalità di misurazione automatica, come la misurazione automatica delle schermate e delle eccezioni non rilevate, utilizzano un solo tracker per inviare i dati a Google Analytics. Se usi queste funzionalità e vuoi inviare dati utilizzando altri tracker, dovrai farlo manualmente.

Uso del tracker predefinito

Google Analytics gestisce un tracker predefinito. Il primo tracker inizializzato diventa il tracker predefinito, ma può essere sostituito:

// Tracker t1 becomes the default tracker because it is initialized first.
Tracker t1 = GoogleAnalytics.getInstance(this).getTracker("UA-XXXX-1");
Tracker t2 = GoogleAnalytics.getInstance(this).getTracker("UA-XXXX-2");


// Returns tracker t1.
Tracker defaultTracker = GoogleAnalytics.getInstance(this).getDefaultTracker();

// Hit sent to UA-XXXX-1.
defaultTracker.send(MapBuilder
    .createAppView()
    .set(Fields.SCREEN_NAME, "Home Screen")
    .build()
);

// Override the default tracker.
GoogleAnalytics.getInstance(this).setDefaultTracker(t2);

// Now this call returns tracker t2.
defaultTracker = GoogleAnalytics.getInstance(this).getDefaultTracker();

// Hit sent to UA-XXXX-2.
defaultTracker.send(MapBuilder
    .createAppView()
    .set(Fields.SCREEN_NAME, getClass().toString())
    .build()
);

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 attivare il campionamento lato client a una frequenza del 50% tramite EasyTracker e XML, utilizza il seguente parametro nel file analytics.xml:

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

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

mTracker.set(Fields.SAMPLE_RATE, 50.0d);

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à NO.

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

Test e debug

L'SDK di Google Analytics per Android fornisce strumenti che semplificano test e 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

L'interfaccia Logger viene fornita per gestire i messaggi utili dell'SDK ai seguenti livelli di dettaglio: error, warning, info e verbose.

L'SDK inizializza un'implementazione Logger standard, che per impostazione predefinita registra solo messaggi di avviso o errore nella console. Questi messaggi saranno disponibili in logcat. Per impostare il livello di dettaglio di Logger:

// Set the log level to verbose.
GoogleAnalytics.getInstance(this).getLogger()
    .setLogLevel(LogLevel.VERBOSE);

Puoi utilizzare anche implementazioni personalizzate di Logger:

// Provide a custom logger.
GoogleAnalytics.getInstance(this).setLogger(new CustomLogger ());

Esempio completo

L'esempio di seguito mostra il codice necessario per inizializzare un'implementazione di Google Analytics e inviare una visualizzazione di schermata singola.

package com.example.app;

import com.google.analytics.tracking.android.GAServiceManager;
import com.google.analytics.tracking.android.GoogleAnalytics;
import com.google.analytics.tracking.android.Tracker;

import android.app.Application;
import android.content.SharedPreferences;
import android.preference.PreferenceManager;


/*
 * An advanced Google Analytics implementation may be initialized
 * in a subclass of Application. Note that this example assumes data
 * only needs to be sent to a single Google Analytics property ID.
 */
public class MyApp extends Application {

  private static GoogleAnalytics mGa;
  private static Tracker mTracker;

  /*
   * Google Analytics configuration values.
   */
  // Placeholder property ID.
  private static final String GA_PROPERTY_ID = "UA-XXXX-Y";

  // Dispatch period in seconds.
  private static final int GA_DISPATCH_PERIOD = 30;

  // Prevent hits from being sent to reports, i.e. during testing.
  private static final boolean GA_IS_DRY_RUN = false;

  // GA Logger verbosity.
  private static final LogLevel GA_LOG_VERBOSITY = LogLevel.INFO;

  // Key used to store a user's tracking preferences in SharedPreferences.
  private static final String TRACKING_PREF_KEY = "trackingPreference";


  /*
   * Method to handle basic Google Analytics initialization. This call will not
   * block as all Google Analytics work occurs off the main thread.
   */
  private void initializeGa() {
    mGa = GoogleAnalytics.getInstance(this);
    mTracker = mGa.getTracker(GA_PROPERTY_ID);

    // Set dispatch period.
    GAServiceManager.getInstance().setLocalDispatchPeriod(GA_DISPATCH_PERIOD);

    // Set dryRun flag.
    mGa.setDryRun(GA_IS_DRY_RUN);

    // Set Logger verbosity.
    mGa.getLogger().setLogLevel(GA_LOG_VERBOSITY);

    // Set the opt out flag when user updates a tracking preference.
    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));
        }
      }
    });
  }

  @Override
  public void onCreate() {
    super.onCreate();
    initializeGa();
  }

  /*
   * Returns the Google Analytics tracker.
   */
  public static Tracker getGaTracker() {
    return mTracker;
  }

  /*
   * Returns the Google Analytics instance.
   */
  public static GoogleAnalytics getGaInstance() {
    return mGa;
  }
}

Successivamente, viene misurata una visualizzazione di schermata quando la prima schermata viene mostrata a un utente:

package com.example.app

import android.app.Activity

/**
 * A simple Activity that sends a screen view to Google Analytics
 * when it is displayed to the user.
 */
public class HomeScreen extends Activity {

  private static final String SCREEN_LABEL = "Home Screen";

  @Override
  public void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);

    // Fields set on a tracker persist for all hits, until they are
    // overridden or cleared by assignment to null.
    MyApp.getGaTracker().set(Fields.SCREEN_NAME, SCREEN_LABEL);
  }

  @Override
  public void onStart() {
    super.onStart();

    // Send a screen view when the Activity is displayed to the user.
    MyApp.getGaTracker().send(MapBuilder
        .createAppView.build());
  }
}