Cấu hình nâng cao – SDK Android

Tài liệu này cung cấp thông tin tổng quan về một số tính năng cấu hình nâng cao của Google Analytics SDK dành cho Android phiên bản 3.

Tổng quan

SDK Google Analytics dành cho Android cung cấp một lớp Tracker để đặt và gửi dữ liệu đến Google Analytics, và một singleton GoogleAnalytics đóng vai trò là giao diện đến các giá trị cấu hình chung của quá trình triển khai của bạn.

Khởi chạy

Để có thể đo lường bất kỳ dữ liệu nào, bạn phải khởi chạy ít nhất một trình theo dõi thông qua singleton GoogleAnalytics bằng cách cung cấp Context và mã tài sản Google Analytics:

// Initialize a tracker using a Google Analytics property ID.
GoogleAnalytics.getInstance(this).getTracker("UA-XXXX-Y")

Giờ đây, bạn có thể dùng công cụ theo dõi này để cài đặt và gửi dữ liệu đến Google Analytics.

Cài đặt và gửi dữ liệu

Dữ liệu được gửi đến Google Analytics bằng cách thiết lập liên kết các cặp thông số-giá trị trên trình theo dõi và gửi dữ liệu đó thông qua phương thức set và 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);

Lớp MapBuilder giúp đơn giản hoá quá trình tạo lượt truy cập và được đề xuất cho hầu hết các trường hợp sử dụng. Ở đây, chúng ta có thể gửi cùng một lượt xem màn hình với ít dòng mã hơn:

// Sending the same screen view hit using MapBuilder.createAppView()
tracker.send(MapBuilder
  .createAppView()
  .set(Fields.SCREEN_NAME, "Home Screen")
  .build()
);

Cú pháp Ampersand của Measurement Protocol

Bạn cũng có thể đặt giá trị cho một lượt truy cập duy nhất, bằng cách đặt giá trị trên Builder hoặc trên tất cả các lượt truy cập tiếp theo, bằng cách đặt giá trị đó trên chính đối tượng trình theo dõi, sử dụng ký hiệu và cú pháp của 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()
);

Để biết danh sách đầy đủ các tham số của Measurement Protocol hiện có, hãy xem Tài liệu tham khảo về tham số Measurement Protocol.

Áp dụng giá trị cho nhiều lần truy cập

Mọi giá trị bạn đặt trực tiếp trên trình theo dõi sẽ được duy trì và áp dụng cho nhiều lượt truy cập, như trong ví dụ sau:

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

Bạn chỉ nên đặt những giá trị mà bạn muốn duy trì trên nhiều lượt truy cập ngay trên công cụ theo dõi. Việc đặt tên màn hình cho trình theo dõi là hợp lý, vì giá trị tương tự có thể được áp dụng cho các lượt xem màn hình và lượt truy cập sự kiện tiếp theo. Tuy nhiên, bạn không nên đặt một trường như loại lượt truy cập trên trình theo dõi, vì trường này có thể sẽ thay đổi theo mỗi lượt truy cập.

Sử dụng nhiều thiết bị theo dõi

Bạn có thể sử dụng nhiều trình theo dõi trong một lần triển khai. Việc này có thể hữu ích trong việc gửi dữ liệu đến nhiều thuộc tính:

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

Các tính năng đo lường tự động (như sàng lọc tự động và đo lường ngoại lệ chưa nắm bắt được) sẽ chỉ sử dụng một trình theo dõi để gửi dữ liệu đến Google Analytics. Nếu đang sử dụng các tính năng này và muốn gửi dữ liệu bằng các công cụ theo dõi khác, bạn cần thực hiện việc này theo cách thủ công.

Sử dụng công cụ theo dõi mặc định

Google Analytics duy trì một trình theo dõi mặc định. Trình theo dõi đầu tiên được khởi tạo sẽ trở thành trình theo dõi mặc định nhưng có thể bị ghi đè:

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

Lấy mẫu

Bạn có thể bật tính năng lấy mẫu phía máy khách để giới hạn số lượt truy cập được gửi đến Google Analytics. Nếu ứng dụng của bạn có số lượng lớn người dùng hoặc gửi một lượng lớn dữ liệu đến Google Analytics, thì việc bật tính năng lấy mẫu sẽ giúp đảm bảo báo cáo không bị gián đoạn.

Ví dụ: để bật tính năng lấy mẫu phía máy khách với tỷ lệ 50% qua EasyTracker và XML, hãy sử dụng tham số sau trong tệp analytics.xml:

<string name="ga_sampleFrequency">50.0</string>

Cách bật tính năng lấy mẫu phía máy khách theo phương thức lập trình cho trình theo dõi:

mTracker.set(Fields.SAMPLE_RATE, 50.0d);

Chọn không tham gia cấp ứng dụng

Bạn có thể bật cờ chọn không sử dụng cấp ứng dụng để vô hiệu hoá Google Analytics trên toàn bộ ứng dụng. Xin lưu ý rằng bạn phải đặt cờ này mỗi khi ứng dụng khởi động và sẽ mặc định là NO.

Để cài đặt chọn không tham gia cấp ứng dụng, hãy sử dụng:

boolean isOptedOut = GoogleAnalytics.getInstance(this).getAppOptOut();

Để thiết lập chế độ chọn không sử dụng ở cấp ứng dụng, hãy sử dụng:

GoogleAnalytics.getInstance(this).setAppOptOut(true);

Trong cách triển khai thông thường, ứng dụng có thể theo dõi thay đổi trong SharedPreferences và cập nhật chế độ cài đặt chọn không sử dụng Google Analytics cho phù hợp:

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

Kiểm tra và gỡ lỗi

Google Analytics SDK dành cho Android cung cấp các công cụ giúp việc kiểm thử và gỡ lỗi dễ dàng hơn.

Chạy thử nghiệm

SDK cung cấp một cờ dryRun mà khi được đặt, cờ này sẽ ngăn gửi dữ liệu đến Google Analytics. Bạn nên đặt cờ dryRun bất cứ khi nào đang kiểm thử hoặc gỡ lỗi một phương thức triển khai và không muốn dữ liệu thử nghiệm xuất hiện trong báo cáo Google Analytics.

Cách thiết lập cờ chạy khô:

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

Trình ghi nhật ký

Giao diện Logger được cung cấp để xử lý các thông báo hữu ích từ SDK ở các mức độ chi tiết sau: error, warning, info và verbose.

SDK khởi chạy một quy trình triển khai Logger tiêu chuẩn. Theo mặc định, SDK sẽ chỉ ghi lại cảnh báo hoặc thông báo lỗi vào bảng điều khiển. Những thông báo này sẽ xuất hiện trong logcat. Cách đặt độ chi tiết của Logger:

// Set the log level to verbose.
GoogleAnalytics.getInstance(this).getLogger()
    .setLogLevel(LogLevel.VERBOSE);

Bạn cũng có thể sử dụng các cách triển khai tuỳ chỉnh của Logger:

// Provide a custom logger.
GoogleAnalytics.getInstance(this).setLogger(new CustomLogger ());

Ví dụ đầy đủ

Ví dụ bên dưới cho thấy mã cần thiết để bắt đầu triển khai Google Analytics và gửi một lượt xem màn hình.

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

Tiếp theo, lượt xem màn hình sẽ được đo khi màn hình đầu tiên hiển thị với người dùng:

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