Google Analytics SDK na Androida v1 (starsza wersja)

Pakiet SDK Google Analytics dla aplikacji mobilnych na Androida ułatwia wdrożenie Google Analytics w aplikacjach na Androida. Z tego dokumentu dowiesz się, jak zintegrować pakiet SDK z aplikacjami.

Omówienie pakietu SDK

Ten pakiet SDK wykorzystuje model śledzenia służący do śledzenia użytkowników w tradycyjnych witrynach i interakcji z widżetami na tradycyjnych stronach internetowych. Z tego powodu użyte poniżej terminy odzwierciedlają konwencjonalny model śledzenia witryny i są mapowane na śledzenie aplikacji mobilnych. Aby zrozumieć, jak działa ten pakiet SDK, musisz wiedzieć, jak działa śledzenie Analytics.

Za pomocą pakietu SDK do śledzenia na urządzeniach mobilnych możesz śledzić aplikacje na telefony za pomocą następujących typów interakcji Analytics:

Śledzenie odsłon
Odsłona to standardowy sposób pomiaru natężenia ruchu w tradycyjnej witrynie. Aplikacje mobilne nie zawierają stron HTML, więc musisz zdecydować, kiedy (i jak często) ma być wysyłane żądanie wyświetlenia strony. Poza tym, ponieważ żądania odsłony są przeznaczone do raportowania danych o strukturach katalogów, musisz podać opisowe nazwy żądań, aby móc korzystać z nazywania ścieżek do stron w raportach dotyczących treści w Analytics. Wybrane nazwy będą widoczne w raportach Analytics jako ścieżki do strony, mimo że nie są to w rzeczywistości strony HTML, ale możesz je wykorzystać, tworząc ścieżki umożliwiające utworzenie dodatkowych grupowań dla wywołań.
Śledzenie zdarzeń
W Analytics zdarzenia służą do śledzenia interakcji użytkowników z elementami strony internetowej w odróżnieniu od żądań wyświetlenia strony. Za pomocą funkcji śledzenia zdarzeń w Google Analytics możesz wykonywać dodatkowe wywołania, które będą raportowane w sekcji Śledzenie zdarzeń w interfejsie raportów Analytics. Zdarzenia są grupowane według kategorii i mogą też korzystać z etykiet poszczególnych zdarzeń, co zapewnia elastyczność raportowania. Na przykład aplikacja multimedialna może mieć w swojej kategorii film działania odtwarzanie/zatrzymanie/wstrzymanie oraz przypisać etykietę do każdej nazwy filmu. Raporty Google Analytics będą sumować zdarzenia dla wszystkich zdarzeń otagowanych kategorią video. Więcej informacji o śledzeniu zdarzeń znajdziesz w przewodniku po śledzeniu zdarzeń.
Śledzenie e-commerce
Korzystaj z funkcji śledzenia e-commerce, aby śledzić transakcje z koszyka na zakupy i zakupy w aplikacji. Aby śledzić transakcję, użyj klasy Transaction do reprezentowania ogólnych informacji o zakupie, a klasy Item do reprezentowania każdego produktu w koszyku. Po zebraniu danych można je wyświetlić w sekcji raportów e-commerce w interfejsie Google Analytics. Więcej informacji o śledzeniu e-commerce znajdziesz w przewodniku po śledzeniu e-commerce.
Zmienne niestandardowe
Zmienne niestandardowe to tagi pary nazwa-wartość, które można wstawiać do kodu śledzenia, aby ulepszać śledzenie w Google Analytics. Więcej informacji o korzystaniu ze zmiennych niestandardowych znajdziesz w przewodniku po zmiennych niestandardowych.

Pierwsze kroki

Wymagania

Aby zintegrować funkcje śledzenia Google Analytics z aplikacją na Androida, potrzebne są:

Konfiguracja

  • Dodaj folder libGoogleAnalytics.jar do katalogu /libs projektu.
  • Dodaj te uprawnienia do pliku manifestu AndroidManifest.xml Twojego projektu:
    • <uses-permission android:name="android.permission.INTERNET" />
    • <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

W pakiecie SDK znajduje się przykładowa aplikacja, która pokazuje, jak powinien wyglądać projekt po udanym skonfigurowaniu. Możesz używać go jako szablonu swoich aplikacji zintegrowanych z Analytics.

Przy użyciu pakietu SDK

Zanim zaczniesz korzystać z pakietu SDK, musisz utworzyć bezpłatne konto na www.google.com/analytics i utworzyć na nim nową usługę internetową, korzystając z fałszywego, ale opisowego adresu URL witryny (np. http://mymobileapp.mywebsite.com). Po utworzeniu usługi zapisz lub zachowaj jej identyfikator wygenerowany dla tej usługi.

Musisz poinformować użytkowników w samej aplikacji lub w warunkach korzystania z usługi, że zastrzegasz sobie prawo do anonimowego śledzenia i zgłaszania aktywności użytkownika wewnątrz aplikacji. Korzystanie z pakietu SDK Google Analytics podlega dodatkowo Warunkom korzystania z usługi Google Analytics, które musisz zaakceptować podczas rejestracji konta.

Przykłady i sprawdzone metody

Przykładowy kod i sprawdzone metody znajdziesz na stronie code.google.com w ramach projektu analytics-api-samples.

Biblioteka EasyTracker

Dostępna jest biblioteka EasyTracker. Zapewnia śledzenie na poziomie aplikacji i działań bez nakładu pracy programistycznej. Znajdziesz go w sekcji Pobrane w projekcie analytics-api-samples.

Uruchamianie trackera

Aby uzyskać singleton trackera, zadzwoń pod numer GoogleAnalyticsTracker.getInstance(). Następnie wywołaj metodę startNewSession, przekazując identyfikator usługi internetowej i śledzoną aktywność. Możesz wywołać tę metodę bezpośrednio w metodzie onCreate aktywności, jeśli aplikacja ma tylko jedną aktywność. Na przykład:

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

Jeśli w aplikacji masz wiele aktywności, możesz skorzystać z biblioteki EasyTracker dostępnej w sekcji Pobrane projektu analytics-api-samples.

Śledzenie odsłon i zdarzeń

Śledzenie wyświetleń stron i zdarzeń jest proste: wystarczy wywołać trackPageView obiektu skryptu śledzenia za każdym razem, gdy chcesz wywołać odsłonę. Zadzwoń pod numer trackEvent, aby nagrać wydarzenie. Więcej informacji o wyświetleniach strony i zdarzeniach znajdziesz w sekcji Omówienie pakietu SDK powyżej.

Używanie zmiennych niestandardowych

Dodanie zmiennej niestandardowej też jest proste – wystarczy użyć metody setCustomVar dostępnej w mobilnym pakiecie SDK. Pamiętaj, by wcześniej zaplanować indeksowanie każdej zmiennej niestandardowej, do której jest mapowana żadna zmienna niestandardowa, by nie zastąpić wcześniej utworzonej zmiennej. Więcej informacji o zmiennych niestandardowych znajdziesz w przewodniku po zmiennych niestandardowych. Pamiętaj, że metoda setCustomVar nie wysyła danych bezpośrednio. Dane są wysyłane przy następnej śledzonej odsłonie lub zdarzeniu. Musisz zadzwonić pod numer setCustomVar przed śledzeniem odsłon lub zdarzeń. Pamiętaj, że domyślny zakres zmiennych niestandardowych jest ograniczony do strony.

Korzystanie ze śledzenia e-commerce

Aby włączyć śledzenie e-commerce w aplikacji, możesz użyć 4 metod:

  • addTransaction
  • addItem
  • trackTransactions
  • clearTransactions

Wywołanie addTransaction i addItem dodaje transakcję lub element do wewnętrznego bufora e-commerce, do którego można dodać więcej elementów i transakcji. Dopiero podczas połączenia z numerem trackTransactions transakcje i produkty zostaną wysłane do dyspozytora i dodane do kolejki do Google Analytics.

Aby wyczyścić bufor, możesz wywołać metodę clearTransactions. Uwaga: system nie pamięta żadnych transakcji wysłanych wcześniej do dyspozytora ani transakcji zebranych już przez Google Analytics.

Ten przykładowy kod pomoże Ci zacząć. Zakładamy, że metoda onPurchaseCompleted jest wywoływana po potwierdzeniu lub odrzuceniu zakupu. 

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

Więcej informacji o e-commerce znajdziesz w Przewodniku śledzenia e-commerce.

Ukryj adres IP

Aby zanonimizować informacje o adresie IP użytkownika, użyj metody setAnonymizeIp. Dzięki temu Google Analytics anonimizuje informacje wysyłane przez pakiet SDK, usuwając ostatni oktet adresu IP poprzedzający przechowywanie.

Możesz zadzwonić pod numer setAnonymizeIp w dowolnej chwili.

Ustawianie częstotliwości próbkowania

Częstotliwość próbkowania możesz ustawić za pomocą metody setSampleRate. Jeśli Twoja aplikacja generuje duży ruch Analytics, ustawienie częstotliwości próbkowania może uniemożliwić generowanie raportów z wykorzystaniem próbkowanych danych. Próbkowanie odbywa się konsekwentnie w przypadku unikalnych użytkowników, co pozwala zachować integralność trendów i raportów, gdy częstotliwość próbkowania jest włączona. Metoda setSampleRate akceptuje 1 parametr int. Prawidłowe wartości tego parametru to dowolna liczba całkowita z zakresu od 0 do 100 włącznie.

Współczynnik równy 0 wyłącza generowanie działań, a współczynnik 100 wysyła wszystkie dane do Google Analytics. Przed wywołaniem jakichkolwiek metod śledzenia najlepiej wywołać metodę setSampleRate.

Więcej informacji na ten temat znajdziesz w poradniku na temat próbkowania.

Działania zbiorcze

Aby zmniejszyć obciążenie połączenia i baterię, zalecamy zebranie żądań śledzenia w grupę. Wywołanie dispatch w obiekcie śledzenia możesz wykonać w każdej chwili, gdy chcesz wysłać żądanie zbiorcze. Możesz to zrobić ręcznie lub w określonych odstępach czasu.

Znane problemy

  • Wywołanie metod GoogleAnalyticsTracker w różnych wątkach może spowodować powstanie nieznanych błędów. Pamiętaj, aby wszystkie połączenia wykonywać w tym samym wątku.

    • Kampanie śledzące

    Pakiet SDK obsługuje dwa rodzaje śledzenia kampanii.

    – Śledzenie kampanii w Google Play – umożliwia śledzenie odesłań instalacji przez Google Play.
    – Ogólne śledzenie kampanii – umożliwia śledzenie dowolnej kampanii kierującej użytkowników do Twojej aplikacji.

    Śledzenie kampanii w Google Play

    Wersja systemu operacyjnego Android 1.6 obsługuje stosowanie parametru adresu URL referrer w linkach pobierania do Google Play. Pakiet Google Analytics SDK dla Androida korzysta z tego parametru, aby automatycznie wypełniać w Google Analytics informacje o kampaniach dla Twojej aplikacji. Umożliwia to zarejestrowanie źródła instalacji aplikacji oraz powiązanie z przyszłymi wyświetleniami strony i zdarzeniami, co może być przydatne np. do oceny skuteczności konkretnej reklamy aplikacji.

    Aby śledzenie odesłań działało, musisz dodać ten fragment kodu do pliku manifestu AndroidManifest.xml swojego projektu:

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

    Aby skonfigurować śledzenie kampanii Google Analytics w Google Play, wygeneruj link odesłania za pomocą poniższego kreatora adresów URL. Użyj linku, aby skierować użytkowników do swojej aplikacji. Pakiet Analytics SDK automatycznie analizuje i rejestruje informacje o witrynie odsyłającej, a potem wypełnia je w raporcie Analytics.

    Aby wygenerować link odesłania, możesz użyć narzędzia Google Play Campaign URL Builder. Nazwa pakietu, Źródło kampanii, Medium kampanii i Nazwa kampanii są wymagane. Szczegółowy opis każdego parametru znajdziesz w tabeli poniżej.

    Ogólne śledzenie kampanii

    Dzięki pakietowi SDK Google Analytics na Androida w wersji 1.3 możesz teraz śledzić kampanie ze źródeł innych niż Google Play. Jeśli np. chcesz wiedzieć, że Twoja aplikacja została uruchomiona po kliknięciu linku w reklamie, możesz poszukać informacji o odesłaniu z kampanii w intencji, która spowodowała jej uruchomienie, a potem zapisać informacje o kampanii w Google Analytics.

    Aby skonfigurować informacje o odesłaniu z kampanii, użyj metody setReferrer w następujący sposób: 

      tracker.setReferrer(referrer);

    Istnieją 2 ograniczenia dotyczące korzystania z tej funkcji. Najpierw musisz zadzwonić pod numer startNewSession, a potem zadzwonić pod numer setReferrer. Musisz to zrobić, ponieważ baza danych SQLite używana przez Google Analytics nie została skonfigurowana przed wywołaniem startNewSession, a setReferrer potrzebuje tej bazy. Jeśli Twoje konto nie zostało nawiązane połączenie startNewSession, otrzymasz IllegalStateException.

    Drugim ograniczeniem jest to, że ciąg odsyłający przekazywany do setReferrer musi mieć określony format. Musi on mieć postać zestawu parametrów adresu URL i zawierać co najmniej jeden parametr gclid lub po jednym z tych parametrów: utm_campaign, utm_medium oraz utm_source. W tym drugim przypadku może też zawierać parametry utm_term i utm_content.

    Parametr gclid jest częścią funkcji automatycznego tagowania, która automatycznie łączy Google Analytics z Google Ads. Przykładowe odesłanie do kampanii korzystające z automatycznego tagowania może wyglądać tak:

    referrer = “gclid=gclidValue”;

    Ciąg znaków odesłania z kampanii ręcznej może wyglądać tak:

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

    Jeśli przekażesz do setReferrer błędnie sformatowany ciąg strony odsyłającej, informacje o stronie odsyłającej nie zostaną zmienione i otrzymasz zwracaną wartość false (fałsz). Zwracana wartość „true” (prawda) wskazuje, że strona odsyłająca została zaktualizowana i będzie dodawana do każdego działania w przyszłości.

    Pamiętaj też, że nowa sesja uruchamia się, gdy wywołasz parametr setReferrer, który zwraca wartość „true”.

    Parametr Wymagane Opis Przykłady
    utm_campaign Tak Nazwa kampanii służy do analizy słów kluczowych w celu identyfikacji określonej promocji produktu lub kampanii strategicznej utm_campaign=spring_sale
    utm_source Tak Źródło kampanii; służy do identyfikowania wyszukiwarki, newslettera lub innego źródła. utm_source=google
    utm_medium Tak Medium kampanii; służy do identyfikacji medium, np. e-maila lub kosztu kliknięcia (cpc) utm_medium=cpc
    utm_term Nie Hasło kampanii; używane w płatnych wynikach wyszukiwania do dostarczania słów kluczowych do reklam utm_term=running+shoes
    utm_content Nie Treść kampanii; używana do testów A/B oraz reklam kierowanych na treść strony w celu rozróżnienia reklam lub linków kierujących do tego samego adresu URL utm_content=logolink
    utm_content=textlink