การกำหนดค่าขั้นสูง - Android SDK

เอกสารนี้แสดงภาพรวมเกี่ยวกับคุณลักษณะการกำหนดค่าขั้นสูงบางอย่างของ Google Analytics SDK สำหรับ Android v3

ภาพรวม

Google Analytics SDK สำหรับ Android มีคลาส Tracker เพื่อตั้งค่าและส่งข้อมูลไปยัง Google Analytics และซิงเกิล GoogleAnalytics ที่ทำหน้าที่เป็นอินเทอร์เฟซสำหรับการกำหนดค่าส่วนกลางของการใช้งาน

การเริ่มต้น

ก่อนที่จะวัดข้อมูลได้ คุณต้องเริ่มต้นเครื่องมือติดตามอย่างน้อย 1 รายการผ่าน GoogleAnalytics Singleton โดยระบุ Context และรหัสพร็อพเพอร์ตี้ Google Analytics ดังนี้

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

แต่ตอนนี้สามารถใช้เครื่องมือติดตามนี้ในการตั้งค่าและส่งข้อมูลไปยัง Google Analytics ได้แล้ว

การตั้งค่าและการส่งข้อมูล

ระบบจะส่งข้อมูลไปยัง Google Analytics โดยการตั้งค่าการแมปคู่พารามิเตอร์-ค่าในเครื่องมือติดตาม และส่งผ่านเมธอด set และ 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);

คลาส MapBuilder ช่วยลดความซับซ้อนของกระบวนการสร้าง Hit และเหมาะสำหรับกรณีการใช้งานส่วนใหญ่ ในส่วนนี้เราจะส่งมุมมองหน้าจอแบบเดียวกันที่มีบรรทัดโค้ดน้อยลงได้ดังนี้

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

ไวยากรณ์ Ampersand ของ Measurement Protocol

นอกจากนี้คุณยังสามารถตั้งค่าสำหรับ Hit เดียวได้โดยตั้งค่าใน Builder หรือสำหรับ Hit ที่ตามมาทั้งหมดโดยการตั้งค่าในออบเจ็กต์เครื่องมือติดตามโดยใช้เครื่องหมายและไวยากรณ์ของ 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()
);

ดูรายการพารามิเตอร์ Measurement Protocol ที่มีอยู่ทั้งหมดได้ที่ข้อมูลอ้างอิงพารามิเตอร์ Measurement Protocol

การใช้ค่ากับ Hit หลายรายการ

ค่าใดๆ ที่ตั้งค่าไว้ในตัวติดตามโดยตรงจะคงอยู่และใช้กับ Hit หลายรายการ ดังตัวอย่างต่อไปนี้

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

ควรตั้งค่าในเครื่องมือติดตามโดยตรงเฉพาะค่าที่คุณต้องการคงไว้ในหลายๆ Hit เท่านั้น การตั้งชื่อหน้าจอในเครื่องมือติดตามก็น่าจะเหมาะสม เนื่องจากสามารถใช้ค่าเดียวกันนี้กับการดูหน้าจอและ Event Hit ที่ตามมาได้ อย่างไรก็ตาม ไม่แนะนําให้ตั้งค่าช่อง เช่น ประเภท Hit บนเครื่องมือติดตาม เนื่องจากมีแนวโน้มว่าจะมีการเปลี่ยนแปลงตาม Hit แต่ละรายการ

การใช้ตัวติดตามหลายอย่าง

อาจใช้เครื่องมือติดตามหลายรายการในการใช้งานครั้งเดียว ซึ่งมีประโยชน์ในการส่งข้อมูลไปยังพร็อพเพอร์ตี้หลายรายการ

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

ฟีเจอร์การวัดผลอัตโนมัติ เช่น หน้าจออัตโนมัติและการวัดข้อยกเว้นที่ไม่ถูกตรวจจับ จะใช้เครื่องมือติดตามเพียงรายการเดียวเพื่อส่งข้อมูลไปยัง Google Analytics หากคุณใช้ฟีเจอร์เหล่านี้และต้องการส่งข้อมูลด้วยเครื่องมือติดตามอื่นๆ คุณต้องดำเนินการด้วยตนเอง

การใช้เครื่องมือติดตามเริ่มต้น

Google Analytics รักษาตัวติดตามเริ่มต้น อุปกรณ์ติดตามแรกที่เริ่มใช้งานจะกลายเป็นเครื่องมือติดตามเริ่มต้น แต่อาจถูกลบล้าง

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

ทดสอบผลิตภัณฑ์

คุณสามารถเปิดใช้การสุ่มตัวอย่างฝั่งไคลเอ็นต์เพื่อจำกัดจำนวน Hit ที่ส่งไปยัง Google Analytics หากแอปมีผู้ใช้จำนวนมากหรือส่งข้อมูลปริมาณมากไปยัง Google Analytics การเปิดใช้การสุ่มตัวอย่างจะช่วยให้การรายงานไม่ขาดตอน

ตัวอย่างเช่น หากต้องการเปิดใช้การสุ่มตัวอย่างฝั่งไคลเอ็นต์ในอัตรา 50% ผ่าน EasyTracker และ XML ให้ใช้พารามิเตอร์ต่อไปนี้ในไฟล์ analytics.xml

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

วิธีเปิดใช้การสุ่มตัวอย่างฝั่งไคลเอ็นต์แบบเป็นโปรแกรมสำหรับตัวติดตามมีดังนี้

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

การเลือกไม่ใช้ระดับแอป

คุณสามารถเปิดใช้แฟล็กการเลือกไม่ใช้ระดับแอปซึ่งจะปิดใช้ Google Analytics ทั่วทั้งแอป โปรดทราบว่าต้องตั้งค่าแฟล็กนี้ทุกครั้งที่แอปเริ่มทำงาน และจะมีค่าเริ่มต้นเป็น NO

หากต้องการรับการตั้งค่าการเลือกไม่ใช้ระดับแอป ให้ใช้

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

หากต้องการตั้งค่าการเลือกไม่ใช้ระดับแอป ให้ใช้ปุ่มต่อไปนี้

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

ในการใช้งานโดยทั่วไป แอปอาจตรวจสอบการเปลี่ยนแปลงใน SharedPreferences และอัปเดตการตั้งค่าการเลือกไม่ใช้ของ 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.
    }
  }
});

การทดสอบและการแก้ไขข้อบกพร่อง

Google Analytics SDK สำหรับ Android มีเครื่องมือที่ช่วยให้การทดสอบและแก้ไขข้อบกพร่องง่ายขึ้น

ทดลองเรียกใช้

SDK ให้แฟล็ก dryRun ซึ่งเมื่อตั้งค่าแล้วจะป้องกันไม่ให้มีการส่งข้อมูลใดๆ ไปยัง Google Analytics คุณควรตั้งค่าแฟล็ก dryRun เมื่อคุณทดสอบหรือแก้ไขข้อบกพร่องของการติดตั้งใช้งาน และไม่ต้องการให้ข้อมูลการทดสอบปรากฏในรายงาน Google Analytics

วิธีตั้งค่าสถานะการทดลองเรียกใช้

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

เครื่องบันทึก

อินเทอร์เฟซ Logger มีไว้เพื่อจัดการข้อความที่เป็นประโยชน์จาก SDK ในระดับการพูดรายละเอียด ได้แก่ error, warning, info และ verbose

SDK เริ่มต้นการใช้งาน Logger มาตรฐาน ซึ่งโดยค่าเริ่มต้นจะบันทึกเฉพาะคําเตือนหรือข้อความแสดงข้อผิดพลาดไปยังคอนโซล ข้อความเหล่านี้จะอยู่ใน Logcat วิธีตั้งค่าการพูดรายละเอียดของ Logger

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

นอกจากนี้คุณยังสามารถใช้การติดตั้งใช้งาน Logger ที่กำหนดเองได้อีกด้วย

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

ตัวอย่างที่สมบูรณ์

ตัวอย่างด้านล่างแสดงโค้ดที่จำเป็นในการเริ่มต้นการติดตั้งใช้งาน Google Analytics และส่งการดูหน้าจอเดียว

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

ถัดไป ระบบจะวัดการดูหน้าจอเมื่อหน้าจอแรกแสดงให้ผู้ใช้เห็น ดังนี้

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