Google Analytics SDK na Androida: przejście na wersję 3

Ważne: w tym dokumencie opisano starszą wersję pakietu SDK. Nowi użytkownicy powinni używać najnowszego pakietu SDK.

Programiści, którzy dopiero zaczynają korzystać z Google Analytics, powinni zacząć korzystać z wersji 3.

Z tego przewodnika dowiesz się, jak zaktualizować pakiet SDK Google Analytics na Androida do wersji 3.

W skrócie: co nowego w wersji 3

Przekształcono interfejsy API w wersji 3, aby były bardziej spójne na platformach natywnych i internetowych. Wszyscy użytkownicy wersji 2 powinni zwrócić uwagę na te zmiany:

• Działania są teraz wysyłane za pomocą pojedynczej metody send(Map<String, String> parameters).
• Tryb debugowania został zastąpiony przez zasadę Logger
• EasyTracker zamienia teraz podklasy Tracker, co spowoduje pewne zmiany w interfejsie.
• Nowość: dodaliśmy flagę dryRun, aby zapobiec wyświetlaniu wysyłanych danych w raportach.

Pełną listę zmian znajdziesz w historii zmian Androida.

Zanim zaczniesz

Przed rozpoczęciem aktualizacji do wersji v3 potrzebne są:

• Usługa z włączoną Universal Analytics i profil aplikacji
• Pakiet Google Analytics SDK na Androida w wersji 3

Ścieżki uaktualnienia

Aby rozpocząć, wybierz ścieżkę uaktualnienia do wersji 3 z bieżącej implementacji:

• EasyTracker: z wersji 1.x do 3
• EasyTracker: z wersji 2.x do 3
• Implementacja niestandardowa: z wersji 1.x do wersji 3
• Implementacja niestandardowa: z wersji 2.x do wersji 3

EasyTracker: od 1.x do 3

Aby rozpocząć korzystanie z wersji v3 z EasyTracker, zalecamy, aby użytkownicy EasyTracker w wersji 1.x zastosowali się do wprowadzenia do wersji 3.

EasyTracker: od wersji 2.x do 3

Aby uaktualnić EasyTracker do wersji 2.x, wykonaj te czynności:

1. Zaktualizuj wywołania funkcji EasyTracker.getInstance(), aby podać: Context:

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

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

2. EasyTracker zawiera teraz podklasy Tracker – usuń wywołania EasyTracker.getTracker():

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

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

3. Zastąp wszystkie wygodne metody send<hit-type> nową metodą 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()
   );
   

   Więcej informacji o wysyłaniu danych w wersji 3



4. Zastąp parametr ga_debug EasyTracker ga_logLevel i jedną z tych wartości szczegółowości: 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>
   

   Więcej informacji znajdziesz w dokumentacji parametrów EasyTracker.



5. Interfejs GoogleAnalytics.requestAppOptOut() został wycofany, ale zamiast niego użyj parametru 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();
   

   Uwaga: w wersji 3 ustawienie rezygnacji na poziomie aplikacji nie jest utrzymywane przez pakiet SDK i trzeba je ustawiać przy każdym uruchomieniu aplikacji. Więcej informacji o konfigurowaniu rezygnacji na poziomie aplikacji
6. (Opcjonalnie) Podczas testowania implementacji dodaj parametr ga_dryRun EasyTracker i ustaw go na true, aby zapobiec wyświetlaniu danych testowych w raportach produkcyjnych:

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

Implementacja niestandardowa: od wersji 1.x do 3

Użytkownicy wersji 1.x, którzy nie używają EasyTracker, powinni wykonać czynności opisane w Przewodniku dla początkujących do wersji 3. W razie potrzeby zapoznaj się z Przewodnikiem dla programistów konfiguracji zaawansowanej.

Implementacja niestandardowa: od wersji 2.x do 3

Użytkownicy wersji 2.x, którzy nie używają EasyTracker, powinni wykonać poniższe czynności, aby przejść na wersję 3:

1. Zastąp wszystkie wygodne metody „send<hit-type>” nową metodą 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. Usuń wywołania funkcji GoogleAnalytics.setDebug(), zastąp tekstem GoogleAnalytics.getLogger().setLogLevel():

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

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

   Więcej informacji o Rejestratorze


3. Pakiet SDK w wersji 3 nie rozpoczyna już automatycznie nowej sesji po otwarciu aplikacji (z wyjątkiem korzystania z EasyTracker). Jeśli chcesz zachować takie zachowanie z implementacji niestandardowej w wersji 2, musisz wdrożyć własną logikę kontroli sesji, gdy użytkownik uruchamia aplikację:

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. (Opcjonalnie) Podczas testowania ustaw flagę dryRun, aby zapobiec przetwarzaniu danych testowych w raportach produkcyjnych:

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

Dokumentacja

W kolejnych sekcjach znajdziesz przykłady konfigurowania i wysyłania danych za pomocą pakietu SDK V3.

Wysyłanie danych przy użyciu Map (wersja 3)

W wersji 3 dane są wysyłane za pomocą pojedynczej metody send(), która wykorzystuje jako argument Map pola i wartości Google Analytics. Aby uprościć proces tworzenia działań, dostępna jest klasa narzędziowa MapBuilder:

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

Klasa MapBuilder może służyć do tworzenia obsługiwanych typów działań, takich jak zdarzenia:

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

Więcej informacji o wysyłaniu danych w wersji 3

Ustawianie danych w trackerze w wersji 3

Wartości można też ustawić bezpośrednio w elemencie Tracker za pomocą metody set(). Wartości ustawione bezpośrednio są stosowane do wszystkich kolejnych działań z tego Tracker:

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

Aby usunąć wartość ustawioną na Tracker, ustaw właściwość null na:

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

Więcej informacji o ustawianiu danych w wersji 3