Ten dokument zawiera przegląd niektórych zaawansowanych funkcji konfiguracyjnych pakietu Google Analytics SDK na Androida w wersji 3.
Przegląd
Pakiet Google Analytics SDK na Androida zawiera klasę Tracker
służącą do ustawiania i wysyłania danych do Google Analytics oraz klasyczną GoogleAnalytics
, która służy jako interfejs do globalnych wartości konfiguracyjnych implementacji.
Zdarzenie inicjujące
Zanim będzie można mierzyć dane, musisz zainicjować co najmniej 1 tag śledzenia za pomocą singletonu GoogleAnalytics
, podając parametry Context
oraz identyfikator usługi Google Analytics:
// Initialize a tracker using a Google Analytics property ID. GoogleAnalytics.getInstance(this).getTracker("UA-XXXX-Y")
Teraz można go używać do konfigurowania i wysyłania danych do Google Analytics.
Ustawianie i wysyłanie danych
Dane są wysyłane do Google Analytics przez ustawienie w module śledzenia map par parametr-wartość i wysyłanie ich za pomocą metod set
i 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);
Klasa MapBuilder
upraszcza proces tworzenia działań i jest zalecana w większości przypadków. Tutaj możemy wysłać ten sam widok ekranu z mniejszą liczbą linijek kodu:
// Sending the same screen view hit using MapBuilder.createAppView() tracker.send(MapBuilder .createAppView() .set(Fields.SCREEN_NAME, "Home Screen") .build() );
Składnia platformy Measurement Protocol
Wartości można też ustawiać dla pojedynczego działania, ustawiając je w Builder
lub dla wszystkich kolejnych działań, ustawiając je w samym obiekcie śledzenia przy użyciu składni ampersand protokołu 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() );
Pełną listę dostępnych parametrów platformy Measurement Protocol znajdziesz w dokumentacji parametrów platformy Measurement Protocol.
Stosowanie wartości do wielu działań
Wszelkie wartości ustawione bezpośrednio w trackerze zostaną zachowane i zastosowane do wielu działań, jak w tym przykładzie:
// 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);
Bezpośrednio w narzędziu do śledzenia należy ustawiać tylko te wartości, które mają być pozostawiane dla wielu działań. Nadanie nazwy ekranu w narzędziu do śledzenia ma sens, ponieważ ta sama wartość może być stosowana do kolejnych wyświetleń ekranu i działań związanych ze zdarzeniem. Nie zalecamy jednak ustawiania w module śledzenia pól takich jak typ trafienia, ponieważ będzie się ono zmieniać z każdym działaniem.
Korzystanie z wielu trackerów
W jednej implementacji można używać wielu skryptów śledzenia, co może być przydatne przy wysyłaniu danych do wielu usług:
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() );
Zautomatyzowane funkcje pomiarowe, takie jak automatyczny pomiar niewykrytych wyjątków i pomiar niewykrytych wyjątków, będą używać tylko jednego trackera do wysyłania danych do Google Analytics. Jeśli korzystasz z tych funkcji i chcesz wysyłać dane za pomocą innych trackerów, musisz to zrobić ręcznie.
Korzystanie z domyślnego trackera
Google Analytics zachowuje domyślny moduł śledzenia. Pierwszy zainicjowany element śledzący staje się domyślnym modułem śledzącym, ale może zostać zastąpiony:
// 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() );
Próbkowanie
Możesz włączyć próbkowanie po stronie klienta, aby ograniczyć liczbę działań wysyłanych do Google Analytics. Jeśli Twoja aplikacja ma dużą liczbę użytkowników lub w inny sposób wysyła do Google Analytics dużą ilość danych, włączenie próbkowania pomoże zapewnić nieprzerwane raportowanie.
Aby na przykład włączyć próbkowanie po stronie klienta z częstotliwością 50% za pomocą EasyTracker i XML, użyj następującego parametru w pliku analytics.xml
:
<string name="ga_sampleFrequency">50.0</string>
Aby włączyć dla skryptu śledzenia próbkowanie po stronie klienta automatycznie:
mTracker.set(Fields.SAMPLE_RATE, 50.0d);
Rezygnacja na poziomie aplikacji
Możesz włączyć flagę rezygnacji na poziomie aplikacji, która spowoduje wyłączenie Google Analytics
w całej aplikacji. Pamiętaj, że tę flagę należy ustawić przy każdym uruchomieniu aplikacji. Domyślna wartość to NO
.
Aby uzyskać ustawienie rezygnacji na poziomie aplikacji:
boolean isOptedOut = GoogleAnalytics.getInstance(this).getAppOptOut();
Aby ustawić rezygnację na poziomie aplikacji:
GoogleAnalytics.getInstance(this).setAppOptOut(true);
W typowej implementacji aplikacja może wychwycić zmianę parametru SharedPreferences
i odpowiednio zaktualizować ustawienie rezygnacji z 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. } } });
Testowanie i debugowanie
Pakiet Google Analytics SDK na Androida udostępnia narzędzia, które ułatwiają testowanie i debugowanie.
Uruchomienie próbne
Pakiet SDK udostępnia flagę dryRun
, która po skonfigurowaniu uniemożliwia wysyłanie danych do Google Analytics. Flaga dryRun
należy ustawić za każdym razem, gdy testujesz lub debugujesz implementację i nie chcesz, aby dane testowe pojawiały się w raportach Google Analytics.
Aby ustawić flagę uruchomienia próbnego:
// 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);
Rejestrator
Interfejs Logger
umożliwia obsługę przydatnych komunikatów z pakietu SDK na tych poziomach szczegółowości: error
, warning
, info
i verbose
.
Pakiet SDK inicjuje standardową implementację Logger
, która domyślnie rejestruje w konsoli tylko ostrzeżenia lub komunikaty o błędach. Te wiadomości będą dostępne w logcat. Aby ustawić szczegółowość interfejsu Logger
:
// Set the log level to verbose. GoogleAnalytics.getInstance(this).getLogger() .setLogLevel(LogLevel.VERBOSE);
Możesz też użyć niestandardowych implementacji elementu Logger
:
// Provide a custom logger. GoogleAnalytics.getInstance(this).setLogger(new CustomLogger ());
Pełny przykład
W przykładzie poniżej pokazujemy kod wymagany do zainicjowania implementacji Google Analytics i wysłania wyświetlenia jednego ekranu.
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; } }
Następnie wyświetlenie ekranu jest mierzone, gdy użytkownik zobaczy pierwszy ekran:
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()); } }