Google Analytics SDK for Android: Migration zu Version 3

In diesem Leitfaden wird beschrieben, wie Sie ein Upgrade auf Version 3 des Google Analytics SDK for Android durchführen.

Live-Anzeige: Neuerungen in V3

Die APIs in V3 wurden refaktoriert, damit sie auf nativen Plattformen und Webplattformen einheitlicher sind. Alle Nutzer der Version 2 sollten diese Änderungen beachten:

• Treffer werden jetzt mit einer einzigen send(Map<String, String> parameters)-Methode gesendet.
• Der Debug-Modus wurde durch „Logger“ ersetzt
• EasyTracker erstellt jetzt eine abgeleitete Klasse von Tracker, was zu einigen Änderungen an der Benutzeroberfläche führt.
• Neu: Das Flag dryRun wurde hinzugefügt, um zu verhindern, dass weitergeleitete Daten in Berichten erscheinen.

Eine vollständige Liste der Änderungen finden Sie im Android-Änderungsprotokoll.

Vorbereitung

Für das Upgrade auf v3 ist Folgendes erforderlich:

• Eine für Universal Analytics aktivierte Property und ein App-Profil
• Google Analytics SDK for Android Version 3

Upgrade-Pfade

Wählen Sie zuerst einen Upgradepfad zu v3 aus Ihrer aktuellen Implementierung aus:

• EasyTracker: Version 1.x bis Version 3
• EasyTracker: Version 2.x bis Version 3
• Benutzerdefinierte Implementierung: Version 1.x bis Version 3
• Benutzerdefinierte Implementierung: Version 2.x bis Version 3

EasyTracker: v1.x bis v3

Nutzer von EasyTracker v1.x sollten dem Startleitfaden für Version 3 folgen, um mit der Verwendung von v3 mit EasyTracker zu beginnen.

EasyTracker: Version 2.x bis Version 3

Nutzer von EasyTracker-Version 2.x sollten die folgenden Schritte ausführen, um das Upgrade auf Version 3 abzuschließen:

1. Aktualisieren Sie die Aufrufe an EasyTracker.getInstance(), um eine Context: anzugeben.

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

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

2. EasyTracker erstellt jetzt abgeleitete Klassen von Tracker. Entfernen Sie Aufrufe von EasyTracker.getTracker():

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

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

3. Ersetzen Sie alle praktischen Methoden send<hit-type> durch die neue Methode 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()
   );
   

   Weitere Informationen zum Senden von Daten in Version 3



4. Ersetzen Sie den EasyTracker-Parameter ga_debug durch ga_logLevel und einen der folgenden Ausführlichkeitswerte: 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>
   

   Weitere Informationen finden Sie in der EasyTracker-Parameterreferenz.



5. GoogleAnalytics.requestAppOptOut() wurde eingestellt. Verwenden Sie stattdessen 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();
   

6. Optional: Fügen Sie beim Testen Ihrer Implementierung den EasyTracker-Parameter ga_dryRun hinzu und setzen Sie diesen auf true, um zu verhindern, dass Testdaten in Ihren Produktionsberichten erscheinen:

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

Benutzerdefinierte Implementierung: Version 1.x bis Version 3

v1.x-Nutzer, die EasyTracker nicht verwenden, sollten den Startleitfaden für V3 und den Entwicklerleitfaden für erweiterte Konfigurationen lesen.

Benutzerdefinierte Implementierung: Version 2.x bis Version 3

v2.x-Nutzer, die EasyTracker nicht verwenden, sollten die folgenden Schritte ausführen, um das Upgrade auf v3 abzuschließen:

1. Ersetzen Sie alle praktischen Methoden „send<hit-type>“ durch die neue Methode 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. Entfernen Sie Aufrufe von GoogleAnalytics.setDebug() und ersetzen Sie sie durch GoogleAnalytics.getLogger().setLogLevel():

   // V2 (Old)
   GoogleAnalytics.getInstance(this).setDebug(true);
   

   // V3
   GoogleAnalytics.getInstance(this)
       .getLogger()
       .setLogLevel(LogLevel.VERBOSE);  // VERBOSE | INFO | DEBUG | WARNING
   

   Weitere Informationen zu Logger


3. Das v3 SDK startet nicht mehr automatisch eine neue Sitzung, wenn die App geöffnet wird (außer bei Verwendung von EasyTracker). Wenn Sie dieses Verhalten einer benutzerdefinierten V2-Implementierung beibehalten möchten, müssen Sie beim Starten der Anwendung eine eigene Sitzungssteuerungslogik implementieren:

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. (Optional) Legen Sie beim Testen das Flag dryRun fest, um zu verhindern, dass Testdaten mit Ihren Produktionsberichten verarbeitet werden:

// When true, dryRun flag prevents data from being processed with reports.
GoogleAnalytics.getInstance(this).setDryRun(true);

Referenz

Die folgenden Abschnitte enthalten Referenzbeispiele zum Festlegen und Senden von Daten mit dem V3 SDK.

Senden von Daten mit Google Maps in Version 3

In V3 werden Daten mit einer einzigen send()-Methode gesendet, die eine Map aus Google Analytics-Feldern und -Werten als Argument verwendet. Es wird eine MapBuilder-Dienstprogrammklasse bereitgestellt, um das Erstellen von Treffern zu vereinfachen:

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

Mit der Klasse MapBuilder können beliebige unterstützte Treffertypen erstellt werden, z. B. Ereignisse:

// Sending an event in v3 using MapBuilder.createEvent()
tracker.send(MapBuilder
    .createEvent("UX", "touch", "menuButton", null)
    .build()
);

Weitere Informationen zum Senden von Daten in Version 3

Daten auf dem Tracker in v3 festlegen

Werte können auch direkt für Tracker mithilfe der Methode set() festgelegt werden. Die direkt festgelegten Werte werden auf alle nachfolgenden Treffer aus dieser Tracker angewendet:

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

Wenn du einen Wert löschen möchtest, der für Tracker festgelegt wurde, setze das Attribut auf 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()
);

Weitere Informationen zum Festlegen von Daten in Version 3