Google Analytics SDK for Android Version 1 (alt)

Mit dem Google Analytics for Mobile Apps SDK for Android können Sie Google Analytics ganz einfach in Android-basierten Apps implementieren. In diesem Dokument wird beschrieben, wie Sie das SDK in Ihre Apps einbinden.

SDK – Übersicht

Dieses SDK verwendet ein Tracking-Modell, das entwickelt wurde, um Nutzer auf herkömmliche Websites zu führen und Interaktionen mit Widgets auf herkömmlichen Webseiten zu erfassen. Daher entsprechen die unten verwendeten Begriffe dem herkömmlichen Website-Tracking-Modell und werden mobilen Apps zugeordnet. Du solltest mit Analytics-Tracking vertraut sein, damit du weißt, wie dieses SDK funktioniert.

Mit dem Mobile Tracking SDK können Sie Ihre Telefonanwendungen mit den folgenden Analytics-Interaktionstypen erfassen:

Tracking von Seitenaufrufen

Ein Seitenaufruf ist eine Standardmethode zum Messen des Trafficvolumens zu einer herkömmlichen Website. Da mobile Apps keine HTML-Seiten enthalten, müssen Sie festlegen, wann und wie oft eine Seitenaufrufanfrage ausgelöst werden soll. Da Anfragen zu Seitenaufrufen dazu dienen, Berichte zu Verzeichnisstrukturen zu erstellen, solltest du ihnen aussagekräftige Namen geben, damit die Namen der Seitenpfade in den Analytics-Berichten zu Inhalten berücksichtigt werden. Die von Ihnen ausgewählten Namen werden in Ihren Analytics-Berichten als Seitenpfade ausgefüllt, obwohl es sich in Wirklichkeit nicht um HTML-Seiten handelt. Sie können dies jedoch zu Ihrem Vorteil nutzen, indem Sie Pfade strukturieren, um zusätzliche Gruppierungen für Ihre Aufrufe bereitzustellen.

Ereignis-Tracking

In Analytics sollen Ereignisse die Nutzerinteraktionen auf Webseitenelemente von Seitenaufrufanfragen unterscheiden. Mit der Ereignis-Tracking-Funktion in Google Analytics kannst du zusätzliche Aufrufe tätigen, die im Bereich „Ereignis-Tracking“ der Analytics-Benutzeroberfläche für Berichte angezeigt werden. Ereignisse werden nach Kategorien gruppiert und können auch Labels pro Ereignis verwenden, was Flexibilität bei der Berichterstellung bietet. So kann beispielsweise eine Multimedia-App die Aktionen play/stop/pause für die Kategorie video haben und für jeden Videonamen ein Label zuweisen. In den Google Analytics-Berichten werden dann Ereignisse für alle Ereignisse zusammengefasst, die mit der Kategorie video gekennzeichnet sind. Weitere Informationen zum Ereignis-Tracking finden Sie im Leitfaden zum Ereignis-Tracking.

E-Commerce-Tracking

Mit der E-Commerce-Tracking-Funktion kannst du Einkaufswagentransaktionen und In-App-Käufe erfassen. Verwenden Sie zum Erfassen einer Transaktion die Klasse Transaction, um die allgemeinen Kaufinformationen zu repräsentieren, und die Klasse Item, um jedes Produkt im Einkaufswagen darzustellen. Nachdem die Daten erfasst wurden, können sie im Bereich „E-Commerce-Berichte“ der Google Analytics-Benutzeroberfläche angesehen werden. Weitere Informationen zum E-Commerce-Tracking findest du im Leitfaden zu E-Commerce-Tracking.

Benutzerdefinierte Variablen

Benutzerdefinierte Variablen sind Name/Wert-Paar-Tags, die Sie zur Optimierung des Google Analytics-Trackings in Ihren Tracking-Code einfügen können. Weitere Informationen zur Verwendung von benutzerdefinierten Variablen findest du im Leitfaden zu benutzerdefinierten Variablen.

Erste Schritte

Voraussetzungen

Wenn Sie die Google Analytics-Tracking-Funktionen in Ihre Android-App einbinden möchten, benötigen Sie Folgendes:

• Android Developer SDK (für Windows, Mac OS X und Linux verfügbar)
• Google Analytics Mobile SDK für Android

Einrichtung

• Fügen Sie libGoogleAnalytics.jar dem Verzeichnis /libs Ihres Projekts hinzu.
• Fügen Sie der Manifestdatei AndroidManifest.xml Ihres Projekts die folgenden Berechtigungen hinzu:
  • <uses-permission android:name="android.permission.INTERNET" />
  • <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

Im SDK ist eine Beispielanwendung enthalten, die zeigt, wie Ihr Projekt nach erfolgreicher Einrichtung aussehen sollte. Sie können sie als Vorlage für Ihre eigenen in Analytics integrierten Apps verwenden.

SDK verwenden

Bevor Sie das SDK verwenden können, müssen Sie zuerst unter www.google.com/analytics ein kostenloses Konto erstellen und in diesem Konto eine neue Web-Property mit einer fiktiven, aber beschreibenden Website-URL erstellen (z.B. http://mymobileapp.mywebsite.com). Notieren Sie sich oder erstellen Sie eine Kopie der Web-Property-ID, die für die neu erstellte Property generiert wurde.

Sie müssen Ihren Nutzern entweder in der App selbst oder in Ihren Nutzungsbedingungen angeben, dass Sie sich das Recht vorbehalten, anonym die Aktivitäten eines Nutzers in Ihrer App nachzuverfolgen und zu melden. Ihre Verwendung des Google Analytics SDK unterliegt außerdem den Google Analytics-Nutzungsbedingungen, denen Sie bei der Registrierung für ein Konto zustimmen müssen.

Beispiele und Best Practices

Beispielcode und Best Practices finden Sie unter code.google.com im Projekt analytics-api-samples.

EasyTracker-Bibliothek

Eine EasyTracker-Bibliothek ist verfügbar. Damit lassen sich Tracking-Informationen auf Anwendungs- und Aktivitätsebene ohne Programmieraufwand erstellen. Sie finden sie im Abschnitt Downloads des Projekts analytics-api-samples.

Der Tracker wird gestartet

Rufen Sie den Tracker-Singleton durch Aufrufen von GoogleAnalyticsTracker.getInstance() ab. Rufen Sie dann die Methode startNewSession auf und übergeben Sie die Web-Property-ID und die zu erfassende Aktivität. Sie können diese Methode direkt in der Methode onCreate Ihrer Aktivität aufrufen, wenn Ihre Anwendung nur eine Aktivität hat. Beispiel:

package com.google.android.apps.analytics.sample;

import com.google.android.apps.analytics.GoogleAnalyticsTracker;

import android.app.Activity;
import android.os.Bundle;
import android.view.View;
import android.view.View.OnClickListener;
import android.widget.Button;

public class TestActivity extends Activity {

  GoogleAnalyticsTracker tracker;

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

    tracker = GoogleAnalyticsTracker.getInstance();

    // Start the tracker in manual dispatch mode...
    tracker.startNewSession("UA-YOUR-ACCOUNT-HERE", this);

    // ...alternatively, the tracker can be started with a dispatch interval (in seconds).
    //tracker.startNewSession("UA-YOUR-ACCOUNT-HERE", 20, this);

    setContentView(R.layout.main);
    Button createEventButton = (Button)findViewById(R.id.NewEventButton);
    createEventButton.setOnClickListener(new OnClickListener() {
      @Override
      public void onClick(View v) {
        tracker.trackEvent(
            "Clicks",  // Category
            "Button",  // Action
            "clicked", // Label
            77);       // Value
      }
    });

    Button createPageButton = (Button)findViewById(R.id.NewPageButton);
    createPageButton.setOnClickListener(new OnClickListener() {
      @Override
      public void onClick(View v) {
        // Add a Custom Variable to this pageview, with name of "Medium" and value "MobileApp" and
        // scope of session-level.
        tracker.setCustomVar(1, "Navigation Type", "Button click", 2);
        // Track a page view. This is probably the best way to track which parts of your application
        // are being used.
        // E.g.
        // tracker.trackPageView("/help"); to track someone looking at the help screen.
        // tracker.trackPageView("/level2"); to track someone reaching level 2 in a game.
        // tracker.trackPageView("/uploadScreen"); to track someone using an upload screen.
        tracker.trackPageView("/testApplicationHomeScreen");
      }
    });

    Button quitButton = (Button)findViewById(R.id.QuitButton);
    quitButton.setOnClickListener(new OnClickListener() {
      @Override
      public void onClick(View v) {
        finish();
      }
    });

    Button dispatchButton = (Button)findViewById(R.id.DispatchButton);
    dispatchButton.setOnClickListener(new OnClickListener() {
      @Override
      public void onClick(View v) {
        // Manually start a dispatch, not needed if the tracker was started with a dispatch
        // interval.
        tracker.dispatch();
      }
    });
  }

  @Override
  protected void onDestroy() {
    super.onDestroy();
    // Stop the tracker when it is no longer needed.
    tracker.stopSession();
  }
}

Wenn Ihre Anwendung mehrere Aktivitäten umfasst, können Sie die EasyTracker-Bibliothek im Abschnitt Downloads des Projekts analytics-api-samples verwenden.

Seitenaufrufe und Ereignisse erfassen

Das Tracking von Seitenaufrufen und Ereignissen ist unkompliziert: Sie rufen einfach jedes Mal trackPageView des Tracker-Objekts auf, wenn Sie einen Seitenaufruf auslösen möchten. Rufe trackEvent auf, um ein Ereignis aufzuzeichnen. Weitere Informationen zu Seitenaufrufen und Ereignissen finden Sie oben unter SDK-Übersicht.

Benutzerdefinierte Variablen verwenden

Benutzerdefinierte Variablen lassen sich ebenfalls ganz einfach hinzufügen: Dazu verwenden Sie einfach die vom Mobile SDK bereitgestellte Methode setCustomVar. Sie sollten vorausplanen, damit die einzelnen benutzerdefinierten Variablen indexiert werden. Vorhandene Variablen werden also nicht überschrieben. Weitere Informationen zu benutzerdefinierten Variablen finden Sie im Leitfaden zu benutzerdefinierten Variablen. Beachten Sie, dass die Methode setCustomVar selbst keine Daten sendet. Vielmehr werden die Daten zusammen mit dem nächsten erfassten Seitenaufruf oder Ereignis gesendet. Sie müssen setCustomVar aufrufen, bevor Sie einen Seitenaufruf oder ein Ereignis erfassen. Der Standardumfang von benutzerdefinierten Variablen ist seitenbezogen.

E-Commerce-Tracking verwenden

Es gibt vier Methoden, mit denen Sie E-Commerce-Tracking in Ihrer Anwendung aktivieren können:

• addTransaction
• addItem
• trackTransactions
• clearTransactions

Durch das Aufrufen von addTransaction und addItem wird die Transaktion oder das Element einem internen E-Commerce-Zwischenspeicher hinzugefügt, dem weitere Elemente und Transaktionen hinzugefügt werden können. Nur wenn trackTransactions aufgerufen wird, werden die Transaktionen und Artikel an den Disziplin gesendet und in die Warteschlange gestellt.

Zum Löschen des Zwischenspeichers können Sie die Methode clearTransactions aufrufen. Hinweis: Es werden keine Transaktionen zurückgerufen, die zuvor an den Dispatcher gesendet wurden, noch Transaktionen, die bereits von Google Analytics erfasst wurden.

Den folgenden Beispielcode können Sie verwenden. Wir gehen davon aus, dass die Methode onPurchaseCompleted aufgerufen wird, wenn der Kauf bestätigt oder abgelehnt wird.

  /**
   * The purchase was processed.  We will track the transaction and its associated line items
   * now, but only if the purchase has been confirmed.
   *
   * @param purchase A PurchaseObject containing all of the transaction information needed to
   *     send the ecommerce hit to Google Analytics.
   */
  public void onPurchaseCompleted(PurchaseObject purchase) {
    tracker.addTransaction(new Transaction.Builder(
        purchase.getTransactionId(),
        purchase.getTotal())
        .setStoreName(purchase.getStoreName())
        .setTotalTax(purchase.getTotalTax())
        .setShippingCost(purchase.getShippingCost())
        .build());
    for (PurchaseLineItem lineItem : purchase.getLineItems()) {
        tracker.addItem(new Item.Builder(
            purchase.getTransactionId(),
            lineItem.getItemSKU(),
            lineItem.getItemCost(),
            lineItem.getQuantity())
            .setItemName(lineItem.getItemName())
            .setItemCategory(lineItem.getItemCategory())
            .build());
    }
    if (purchase.isConfirmed()) {
      tracker.trackTransactions();
    } else {
      // The purchase was denied or failed in some way.  We need to clear out
      // any data we've already put in the Ecommerce buffer.
      tracker.clearTransactions();
    }
  }

Weitere Informationen zum E-Commerce

IP-Anonymisierung

Verwenden Sie die Methode setAnonymizeIp, um Nutzer-IP-Informationen zu anonymisieren. Dadurch wird Google Analytics angewiesen, die vom SDK gesendeten Informationen zu anonymisieren. Dabei wird das letzte Oktett der IP-Adresse vor dem Speichern entfernt.

Du kannst setAnonymizeIp jederzeit anrufen.

Abtastrate festlegen

Sie können die Abtastrate mit der Methode setSampleRate festlegen. Wenn in Ihrer Anwendung viele Analytics-Zugriffe generiert werden, kann die Festlegung der Abtastrate dazu führen, dass Ihre Berichte nicht anhand von Stichprobendaten erstellt werden. Die Stichprobenerhebung wird konsequent bei einzelnen Nutzern durchgeführt. Daher sind die Trends und die Berichte einheitlich, wenn die Abtastrate aktiviert ist. Die Methode setSampleRate akzeptiert einen int-Parameter. Gültige Werte für diesen Parameter sind beliebige Ganzzahlen zwischen 0 und 100.

Bei einer Rate von 0 wird die Treffergenerierung deaktiviert, bei einer Rate von 100 werden alle Daten an Google Analytics gesendet. Am besten rufen Sie setSampleRate auf, bevor Sie Tracking-Methoden aufrufen.

Weitere Informationen zur Stichprobenerhebung finden Sie im Leitfaden zu Stichprobenkonzepten.

Batch-Treffer

Wir empfehlen Ihnen, Ihre Tracking-Anfragen in Batches zusammenzufassen, um die Verbindung und den Akkuverbrauch zu verringern. Sie können dispatch für das Tracking-Objekt jederzeit aufrufen, wenn Sie eine Batchanfrage stellen möchten – entweder manuell oder in bestimmten Zeitintervallen.

Bekannte Probleme

Der Aufruf von GoogleAnalyticsTracker-Methoden in verschiedenen Threads kann zu unklaren Fehlern führen. Achten Sie darauf, dass Sie alle Anrufe aus demselben Thread tätigen.

Tracking-Kampagnen

Das SDK unterstützt zwei Arten von Kampagnen-Tracking.

– Kampagnen-Tracking in Google Play: Damit können Sie Installationsempfehlungen über Google Play erfassen.
– Allgemeines Kampagnen-Tracking: Damit können Sie alle Kampagnen erfassen, die Nutzer auf Ihre App verweisen.

Google Play-Kampagnen-Tracking

Die Android-Version 1.6 unterstützt die Verwendung eines referrer-URL-Parameters in Download-Links zu Google Play. Das Google Analytics SDK for Android verwendet diesen Parameter, um Kampagneninformationen für Ihre App automatisch in Google Analytics auszufüllen. Dadurch kann die Quelle der App-Installation aufgezeichnet und zukünftigen Seitenaufrufen und Ereignissen zugeordnet werden. So lässt sich beispielsweise die Effektivität einer bestimmten Anzeige für Ihre App beurteilen.

Damit das Empfehlungs-Tracking funktioniert, müssen Sie das folgende Code-Snippet in die Manifestdatei AndroidManifest.xml Ihres Projekts einfügen:

<!-- Used for install referrer tracking -->
<receiver android:name="com.google.android.apps.analytics.AnalyticsReceiver" android:exported="true">
  <intent-filter>
    <action android:name="com.android.vending.INSTALL_REFERRER" />
  </intent-filter>
</receiver>

Verwenden Sie zum Einrichten des Google Analytics-Kampagnen-Trackings über Google Play das Tool zur URL-Erstellung unten, um einen Empfehlungslink zu generieren. Verwenden Sie den Link, um Nutzer auf Ihre App zu verweisen. Das Analytics SDK parst die Verweisinformationen automatisch und zeichnet es auf und gibt sie in Ihren Analytics-Bericht ein.

Zum Generieren des Empfehlungslinks verwenden Sie das Tool zur URL-Erstellung für Kampagnen von Google Play. Paketname, Kampagnenquelle, Kampagnenmedium und Kampagnenname sind erforderlich. Eine ausführliche Beschreibung der einzelnen Parameter finden Sie in der Tabelle unten.

Kampagnen-Tracking

In Version 1.3 des Google Analytics SDK für Android können Kampagnen jetzt auch für andere Quellen als Google Play erfasst werden. Wenn Sie beispielsweise wissen möchten, dass Ihre App über einen Link in einer Anzeige gestartet wurde, können Sie in der Absicht nach dem Start Ihrer App nach Kampagnenverweisinformationen suchen und diese Kampagneninformationen dann in Google Analytics speichern.

Verwenden Sie zum Festlegen der Kampagnenverweisinformationen die Methode setReferrer so:

  tracker.setReferrer(referrer);

Für diese Funktion gelten zwei Einschränkungen. Sie müssen zuerst startNewSession aufrufen, bevor Sie setReferrer aufrufen. Dieser Schritt ist erforderlich, da die von Google Analytics verwendete SQLite-Datenbank nicht vor dem Aufruf von startNewSession eingerichtet wird und setReferrer diese Datenbank benötigt. Wenn Sie startNewSession nicht aufgerufen haben, erhalten Sie ein IllegalStateException.

Die zweite Einschränkung besteht darin, dass der an setReferrer übergebene Verweisstring ein bestimmtes Format haben muss. Er muss die Form eines URL-Parametersatzes haben und mindestens einen gclid-Parameter oder einen der Parameter „utm_campaign“, „utm_medium“ und „utm_source“ enthalten. Im letzteren Fall können auch die Parameter „utm_term“ und „utm_content“ enthalten sein.

Der Parameter „gclid“ ist Teil der automatischen Tag-Kennzeichnung. Damit werden Google Analytics automatisch mit Google Ads verknüpft. Ein Beispiel für einen Kampagnenverweis mit dem automatischen Tagging könnte so aussehen:

referrer = “gclid=gclidValue”;

Der String für den manuellen Kampagnenverweis könnte so aussehen:

referrer = “utm_campaign=campaign&utm_source=source&utm_medium=medium&utm_term=term&utm_content=content”;

Wenn Sie einen ungültigen Verweis-URL-String an setReferrer übergeben, werden die Verweisinformationen nicht geändert und Sie erhalten den Rückgabewert „false“. Der Rückgabewert "true" gibt an, dass die Verweis-URL aktualisiert wurde, und wird jedem Treffer in Zukunft hinzugefügt.

Wenn Sie setReferrer aufrufen, wird eine neue Sitzung gestartet und „true“ zurückgegeben.

Parameter für Empfehlungslinks

Parameter	Required	Beschreibung	Beispiel(e)
utm_campaign	Ja	Kampagnenname; wird für die Keyword-Analyse verwendet, um eine bestimmte Produktwerbung oder strategische Kampagne zu identifizieren	utm_campaign=spring_sale
utm_source	Ja	Kampagnenquelle; dient zur Identifizierung einer Suchmaschine, eines Newsletters oder einer anderen Quelle	utm_source=google
utm_medium	Ja	Kampagnenmedium; wird verwendet, um ein Medium wie E-Mail oder Cost-per-Click (CPC) zu identifizieren	utm_medium=cpc
utm_term	Nein	Kampagnenbegriff; wird zusammen mit der bezahlten Suche verwendet, um die Keywords für Anzeigen bereitzustellen	utm_term=running+shoes
utm_content	Nein	Kampagneninhalte; werden für A/B-Tests und inhaltsbezogene Anzeigen verwendet, um Anzeigen oder Links zu unterscheiden, die auf dieselbe URL verweisen	utm_content=logolink utm_content=textlink