Google Analytics SDK สำหรับ Android: การย้ายข้อมูลไปยัง v3

คู่มือนี้อธิบายวิธีอัปเกรด Google Analytics SDK สำหรับ Android เป็นเวอร์ชัน 3

ข้อมูลโดยย่อ: มีอะไรใหม่ใน V3

API ในเวอร์ชัน 3 ได้รับการปรับโครงสร้างใหม่ให้สอดคล้องกันมากขึ้นในแพลตฟอร์มเนทีฟและเว็บ ผู้ใช้เวอร์ชัน 2 ทุกคนควรทราบการเปลี่ยนแปลงต่อไปนี้

  • ตอนนี้ระบบจะส่ง Hit โดยใช้เมธอด send(Map<String, String> parameters) เพียงวิธีเดียว
  • ระบบได้แทนที่โหมดแก้ไขข้อบกพร่องด้วย Logger แล้ว
  • ตอนนี้ EasyTracker มีคลาสย่อย Tracker ซึ่งส่งผลให้อินเทอร์เฟซมีการเปลี่ยนแปลง
  • ใหม่: มีการเพิ่มแฟล็ก dryRun เพื่อป้องกันไม่ให้ข้อมูลที่จัดส่งปรากฏในรายงาน

ดูรายการการเปลี่ยนแปลงทั้งหมดได้ที่ Android Changelog

ก่อนที่คุณจะเริ่ม

ก่อนเริ่มอัปเกรดเป็น v3 คุณต้องมีสิ่งต่อไปนี้

เส้นทางการอัปเกรด

หากต้องการเริ่มต้นใช้งาน ให้เลือกเส้นทางการอัปเกรดเป็นเวอร์ชัน 3 จากการใช้งานปัจจุบัน ดังนี้

EasyTracker: v1.x ถึง v3

ขอแนะนำให้ผู้ใช้ EasyTracker v1.x ทำตามคู่มือเริ่มต้นใช้งาน v3 เพื่อเริ่มใช้ v3 กับ EasyTracker

EasyTracker: v2.x ถึง v3

ผู้ใช้ EasyTracker v2.x ควรทำตามขั้นตอนต่อไปนี้เพื่ออัปเกรดเป็น v3 ให้เสร็จสมบูรณ์

  1. อัปเดตการโทรไปยัง EasyTracker.getInstance() เพื่อระบุ Context: 
    // v2 (Old)
// EasyTracker.getInstance().activityStart(this);

    // v3:
EasyTracker.getInstance(this).activityStart(this);
  2. ตอนนี้ EasyTracker ในคลาสย่อย Tracker นำการเรียก ไปยัง EasyTracker.getTracker() ออก: 
    // v2 (Old)
Tracker v2Tracker = EasyTracker.getInstance().getTracker();

    // v3
Tracker v3Tracker = EasyTracker.getInstance(this);
  3. แทนที่วิธีการอำนวยความสะดวก send<hit-type> ทั้งหมดด้วยเมธอด 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()
);
    ดูข้อมูลเพิ่มเติมเกี่ยวกับการส่งข้อมูลใน v3


  4. แทนที่พารามิเตอร์ ga_debug EasyTracker ด้วย ga_logLevel และค่ารายละเอียดต่อไปนี้ 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>
    ดูรายละเอียดเพิ่มเติมในข้อมูลอ้างอิงพารามิเตอร์ EasyTracker


  5. GoogleAnalytics.requestAppOptOut() เลิกใช้งานแล้ว ให้ใช้ 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();
  6. (ไม่บังคับ) เพิ่มพารามิเตอร์ EasyTracker ga_dryRun และตั้งค่าเป็น true เมื่อทดสอบการใช้งานเพื่อป้องกันไม่ให้ข้อมูลการทดสอบปรากฏในรายงานที่ใช้งานจริง
    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>

การใช้งานที่กำหนดเอง: เวอร์ชัน 1.x ถึง v3

ผู้ใช้เวอร์ชัน 1.x ที่ไม่ได้ใช้ EasyTracker ควรปฏิบัติตามคู่มือเริ่มต้นใช้งาน V3 และดูคู่มือนักพัฒนาซอฟต์แวร์การกำหนดค่าขั้นสูงตามที่จำเป็น

การใช้งานที่กำหนดเอง: เวอร์ชัน 2.x ถึง v3

ผู้ใช้เวอร์ชัน 2.x ที่ไม่ได้ใช้ EasyTracker ควรทำตามขั้นตอนด้านล่างเพื่ออัปเกรดเป็น v3 ให้เสร็จสมบูรณ์

  1. แทนที่วิธีการอำนวยความสะดวก "send<hit-type>" ทั้งหมดด้วยเมธอด 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. นำการเรียกไปยัง GoogleAnalytics.setDebug() ออกและแทนที่ด้วย GoogleAnalytics.getLogger().setLogLevel(): 
    // V2 (Old)
GoogleAnalytics.getInstance(this).setDebug(true);

    // V3
GoogleAnalytics.getInstance(this)
    .getLogger()
    .setLogLevel(LogLevel.VERBOSE);  // VERBOSE | INFO | DEBUG | WARNING
    ดูข้อมูลเพิ่มเติมเกี่ยวกับ Logger

  3. SDK v3 จะไม่เริ่มเซสชันใหม่โดยอัตโนมัติอีกต่อไปเมื่อแอปเปิดขึ้น (ยกเว้นเมื่อใช้ EasyTracker) หากต้องการคงลักษณะการทำงานนี้จากการติดตั้งใช้งานที่กำหนดเอง V2 ไว้ คุณจะต้องใช้ตรรกะการควบคุมเซสชันของคุณเองเมื่อผู้ใช้เริ่มต้นแอป ดังนี้
    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. (ไม่บังคับ) ตั้งค่าแฟล็ก dryRun ขณะทดสอบเพื่อป้องกันไม่ให้ระบบประมวลผลข้อมูลทดสอบด้วยรายงานที่ใช้งานจริง ดังนี้
    5. // When true, dryRun flag prevents data from being processed with reports.
GoogleAnalytics.getInstance(this).setDryRun(true);

ข้อมูลอ้างอิง

ส่วนต่อไปนี้ให้ตัวอย่างอ้างอิงวิธีตั้งค่าและส่งข้อมูลโดยใช้ SDK เวอร์ชัน 3

การส่งข้อมูลโดยใช้ Maps ในเวอร์ชัน 3

ใน V3 ระบบจะส่งข้อมูลโดยใช้เมธอด send() เดียวซึ่งนำ Map ของช่องและค่าของ Google Analytics เป็นอาร์กิวเมนต์ คลาสยูทิลิตี MapBuilder มีไว้เพื่อลดความซับซ้อนของกระบวนการสร้าง 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.
);

คุณใช้คลาส MapBuilder เพื่อสร้างประเภท Hit ใดก็ได้ที่รองรับ เช่น เหตุการณ์

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

ดูข้อมูลเพิ่มเติมเกี่ยวกับการส่งข้อมูลในเวอร์ชัน 3

การตั้งค่าข้อมูลเกี่ยวกับเครื่องมือติดตามใน v3

นอกจากนี้คุณยังตั้งค่าใน Tracker ได้โดยตรงโดยใช้เมธอด set() ค่าที่ตั้งไว้จะมีผลกับ Hit ที่ตามมาทั้งหมดจากค่านั้นโดยตรง 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()
);

หากต้องการล้างค่าที่ตั้งไว้ใน Tracker ให้ตั้งค่าพร็อพเพอร์ตี้เป็น 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()
);

ดูข้อมูลเพิ่มเติมเกี่ยวกับการตั้งค่าข้อมูลในเวอร์ชัน 3