Google Analytics SDK untuk Android: Bermigrasi ke v3

Panduan ini menjelaskan cara mengupgrade Google Analytics SDK untuk Android ke V3.

Sekilas: Yang Baru di V3

API di V3 telah difaktorkan ulang agar lebih konsisten di seluruh platform native dan web. Semua pengguna V2 harus memperhatikan perubahan ini:

  • Kini hit dikirim menggunakan satu metode send(Map<String, String> parameters).
  • Mode debug telah diganti dengan Logger
  • EasyTracker kini membuat subclass Tracker, sehingga menghasilkan beberapa perubahan pada antarmuka.
  • Baru: Flag dryRun telah ditambahkan untuk mencegah data yang dikirim muncul dalam laporan.

Untuk mengetahui daftar lengkap perubahan, lihat Log Perubahan Android.

Sebelum Memulai

Sebelum memulai upgrade ke v3, Anda memerlukan hal berikut:

Jalur Upgrade

Untuk memulai, pilih jalur upgrade ke v3 dari implementasi Anda saat ini:

EasyTracker: v1.x hingga v3

Sebaiknya pengguna EasyTracker v1.x mengikuti Panduan Memulai v3 untuk mulai menggunakan v3 dengan EasyTracker.

EasyTracker: v2.x hingga v3

Pengguna EasyTracker v2.x harus mengikuti langkah-langkah berikut untuk menyelesaikan upgrade ke v3:

  1. Perbarui panggilan ke EasyTracker.getInstance() untuk memberikan Context: 
    // v2 (Old)
// EasyTracker.getInstance().activityStart(this);

    // v3:
EasyTracker.getInstance(this).activityStart(this);
  2. EasyTracker kini subclass dari Tracker -- menghapus panggilan ke EasyTracker.getTracker(): 
    // v2 (Old)
Tracker v2Tracker = EasyTracker.getInstance().getTracker();

    // v3
Tracker v3Tracker = EasyTracker.getInstance(this);
  3. Ganti semua metode praktis send<hit-type> dengan metode send(Map<String, String> parameters) baru: 
    // 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()
);
    Pelajari lebih lanjut cara mengirim data di v3.


  4. Ganti parameter EasyTracker ga_debug dengan ga_logLevel, dan salah satu nilai panjang berikut: 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>
    Lihat Referensi Parameter EasyTracker untuk detail selengkapnya.


  5. GoogleAnalytics.requestAppOptOut() tidak digunakan lagi, gunakan GoogleAnalytics.getAppOptOut() sebagai gantinya: 
    // 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. (Opsional) Tambahkan parameter EasyTracker ga_dryRun dan tetapkan ke true saat menguji implementasi agar data pengujian tidak muncul dalam laporan produksi Anda:
    7. <!-- 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>

Implementasi Kustom: v1.x hingga v3

Pengguna v1.x yang tidak menggunakan EasyTracker harus mengikuti Panduan Memulai V3 dan membaca Panduan Developer Konfigurasi Lanjutan jika diperlukan.

Implementasi Kustom: v2.x hingga v3

Pengguna v2.x yang tidak menggunakan EasyTracker harus mengikuti langkah-langkah di bawah ini untuk menyelesaikan upgrade ke v3:

  1. Ganti semua metode praktis 'send<hit-type>' dengan metode send(Map<String, String> parameters) baru: 
    // 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. Hapus panggilan ke GoogleAnalytics.setDebug(), ganti dengan GoogleAnalytics.getLogger().setLogLevel(): 
    // V2 (Old)
GoogleAnalytics.getInstance(this).setDebug(true);

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

  3. SDK v3 tidak lagi otomatis memulai sesi baru saat aplikasi terbuka (kecuali saat menggunakan EasyTracker). Jika ingin mempertahankan perilaku ini dari penerapan kustom v2, Anda harus menerapkan logika kontrol sesi Anda sendiri saat pengguna memulai aplikasi:
    4. 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. (Opsional) Tetapkan flag dryRun saat menguji agar data pengujian tidak diproses dengan laporan produksi Anda:
    5. // When true, dryRun flag prevents data from being processed with reports.
GoogleAnalytics.getInstance(this).setDryRun(true);

Referensi

Bagian berikut memberikan contoh referensi tentang cara menetapkan dan mengirim data menggunakan SDK V3.

Mengirim Data menggunakan Maps di v3

Di V3, data dikirim menggunakan satu metode send() yang mengambil Map kolom dan nilai Google Analytics sebagai argumen. Class utilitas MapBuilder disediakan untuk menyederhanakan proses pembuatan hit:

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

Class MapBuilder dapat digunakan untuk membuat salah satu jenis hit yang didukung, seperti peristiwa:

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

Pelajari lebih lanjut cara Mengirim Data di v3.

Menetapkan Data di Pelacak di v3

Nilai juga dapat ditetapkan secara langsung pada Tracker menggunakan metode set(). Nilai yang ditetapkan secara langsung akan diterapkan ke semua hit berikutnya dari 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()
);

Untuk menghapus nilai yang telah ditetapkan di Tracker, tetapkan properti ini ke 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()
);

Pelajari lebih lanjut cara Menetapkan Data di v3