Erweiterte Konfiguration – Android SDK

Dieses Dokument bietet einen Überblick über einige der erweiterten Konfigurationsfunktionen des Google Analytics SDK for Android Version 3.

Überblick

Das Google Analytics SDK for Android bietet eine Tracker -Klasse zum Festlegen und Senden von Daten an Google Analytics sowie einen GoogleAnalytics -Singleton, der als Schnittstelle zu den globalen Konfigurationswerten Ihrer Implementierung dient.

Initialisierung

Bevor Daten gemessen werden können, müssen Sie mindestens einen Tracker über einen GoogleAnalytics-Singleton initialisieren. Geben Sie dazu einen Context und eine Google Analytics-Property-ID an:

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

Jetzt können mit diesem Tracker Daten festgelegt und an Google Analytics gesendet werden.

Daten festlegen und senden

Daten werden an Google Analytics gesendet, indem Zuordnung von Parameter/Wert-Paaren auf dem Tracker festgelegt und über die Methoden set und send gesendet wird:

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

Die Klasse MapBuilder vereinfacht das Erstellen von Treffern und wird für die meisten Anwendungsfälle empfohlen. Hier können wir dieselbe Bildschirmansicht mit weniger Codezeilen senden:

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

kaufmännisches Und-Zeichen (Measurement Protocol)

Werte können auch für einen einzelnen Treffer oder durch Festlegen des Werts für einen Builder oder für alle nachfolgenden Treffer festgelegt werden, indem Sie ihn mithilfe des Et-Zeichens des Measurement Protocol im Tracker-Objekt selbst festlegen:

// Setting the content description field on a single hit using ampersand syntax.
tracker.send(MapBuilder
  .createAppView()
  .set(Fields.SCREEN_NAME, "Home Screen")
  .build()
);

Eine vollständige Liste der verfügbaren Measurement Protocol-Parameter finden Sie in der Referenz zu Measurement Protocol-Parametern.

Werte auf mehrere Treffer anwenden

Alle Werte, die direkt im Tracker festgelegt werden, werden beibehalten und auf mehrere Treffer angewendet, wie in diesem Beispiel:

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

Nur Werte, die für mehrere Treffer beibehalten werden sollen, sollten direkt im Tracker festgelegt werden. Es wäre sinnvoll, einen Bildschirmnamen für einen Tracker festzulegen, da derselbe Wert auf nachfolgende Bildschirmaufrufe und Ereignistreffer angewendet werden kann. Es wird jedoch nicht empfohlen, auf dem Tracker ein Feld wie den Treffertyp festzulegen, da es sich wahrscheinlich mit jedem Treffer ändert.

Mehrere Tracker verwenden

In einer einzelnen Implementierung können mehrere Tracker verwendet werden, was beim Senden von Daten an mehrere Properties nützlich sein kann:

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

Bei automatischen Messfunktionen wie der automatischen Filterung und der Messung nicht erfasster Ausnahmen wird nur ein Tracker verwendet, um Daten an Google Analytics zu senden. Wenn du diese Funktionen verwendest und Daten mit anderen Trackern senden möchtest, musst du dies manuell tun.

Verwenden des Standard-Trackers

In Google Analytics wird ein Standard-Tracker verwendet. Der erste initialisierte Tracker wird zum Standard-Tracker, kann aber überschrieben werden:

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

Probenahme

Sie können die clientseitige Stichprobenerhebung aktivieren, um die Anzahl der Treffer zu begrenzen, die an Google Analytics gesendet werden. Wenn Ihre Anwendung eine große Anzahl von Nutzern hat oder anderweitig ein großes Datenvolumen an Google Analytics sendet, können Sie durch Aktivieren der Stichprobenerhebung eine unterbrechungsfreie Berichterstellung gewährleisten.

Wenn Sie beispielsweise clientseitige Stichproben mit einer Rate von 50% über EasyTracker und XML aktivieren möchten, verwenden Sie den folgenden Parameter in Ihrer analytics.xml-Datei:

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

So aktivieren Sie clientseitige Stichproben für einen Tracker programmatisch:

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

Deaktivierung auf App-Ebene

Sie können ein Deaktivierungs-Flag auf App-Ebene aktivieren, durch das Google Analytics für die gesamte App deaktiviert wird. Dieses Flag muss bei jedem Start der App gesetzt werden und wird standardmäßig auf NO gesetzt.

So rufen Sie die Deaktivierungseinstellung auf App-Ebene ab:

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

So legen Sie die Deaktivierung auf App-Ebene fest:

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

In einer typischen Implementierung kann eine App auf eine Änderung in SharedPreferences warten und die Google Analytics-Deaktivierungseinstellung entsprechend aktualisieren:

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

Testen und Fehler beheben

Das Google Analytics SDK for Android bietet Tools, die das Testen und die Fehlerbehebung erleichtern.

Probelauf

Im SDK wird das Flag dryRun bereitgestellt, das verhindert, dass Daten an Google Analytics gesendet werden. Das Flag dryRun sollte immer dann gesetzt werden, wenn Sie eine Implementierung testen oder Fehler beheben und die Testdaten nicht in Ihren Google Analytics-Berichten erscheinen sollen.

So legen Sie das Probelauf-Flag fest:

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

Die Schnittstelle Logger wird zur Verarbeitung nützlicher Meldungen vom SDK mit folgenden Ausführlichkeitsstufen bereitgestellt: error, warning, info und verbose.

Das SDK initialisiert eine Logger-Standardimplementierung, die standardmäßig nur Warnungen oder Fehlermeldungen in der Console protokolliert. Diese Nachrichten sind in Logcat verfügbar. So legen Sie die Ausführlichkeit von Logger fest:

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

Benutzerdefinierte Implementierungen von Logger können auch verwendet werden:

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

Vollständiges Beispiel

Im folgenden Beispiel sehen Sie den Code, der zum Initialisieren einer Google Analytics-Implementierung und zum Senden eines einzelnen Bildschirmaufrufs erforderlich ist.

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

Als Nächstes wird ein Bildschirmaufruf gemessen, wenn einem Nutzer der erste Bildschirm angezeigt wird:

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