Kể từ ngày 1 tháng 7 năm 2023, các tài sản Universal Analytics (UA) chuẩn đã ngừng xử lý dữ liệu. Tài sản UA 360 sẽ ngừng xử lý dữ liệu kể từ ngày 1 tháng 7 năm 2024, và một số tính năng của UA 360 sẽ ngừng hoạt động trước thời điểm đó khi chúng tôi chuyển sang Google Analytics 4. Để sử dụng Google Analytics 4, hãy di chuyển sang Firebase.

Trang này được dịch bởi Cloud Translation API.

Google Analytics SDK dành cho Android: Di chuyển sang phiên bản 3

Hướng dẫn này mô tả cách nâng cấp lên SDK Google Analytics dành cho Android phiên bản 3.

Xem nhanh: Tính năng mới trong phiên bản 3

Các API trong phiên bản 3 đã được tái cấu trúc để nhất quán hơn trên các nền tảng gốc và web. Tất cả người dùng phiên bản 2 cần lưu ý những thay đổi sau:

Các lượt truy cập hiện được gửi bằng một phương thức send(Map<String, String> parameters) duy nhất.
Chế độ gỡ lỗi đã được thay thế bằng Logger
EasyTracker hiện phân lớp con Tracker, dẫn đến một số thay đổi đối với giao diện.
Mới: Một cờ dryRun đã được thêm vào để ngăn dữ liệu đã gửi xuất hiện trong báo cáo.

Để xem danh sách đầy đủ các thay đổi, hãy xem Nhật ký thay đổi Android.

Trước khi bạn bắt đầu

Trước khi bắt đầu nâng cấp lên phiên bản 3, bạn sẽ cần:

Lộ trình nâng cấp

Để bắt đầu, hãy chọn một đường dẫn nâng cấp lên v3 trong cách triển khai hiện tại của bạn:

EasyTracker: từ v1.x đến v3
EasyTracker: từ phiên bản 2.x đến phiên bản 3
Triển khai tuỳ chỉnh: phiên bản 1.x đến phiên bản 3
Triển khai tuỳ chỉnh: phiên bản 2.x đến phiên bản 3

EasyTracker: v1.x sang v3

Người dùng EasyTracker v1.x nên làm theo Hướng dẫn bắt đầu sử dụng v3 để bắt đầu sử dụng v3 với EasyTracker.

EasyTracker: v2.x sang v3

Người dùng EasyTracker v2.x nên làm theo các bước sau để hoàn tất việc nâng cấp lên v3:

Cập nhật lệnh gọi thành EasyTracker.getInstance() để cung cấp một Context:

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

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

EasyTracker hiện là các lớp con Tracker -- xoá các lệnh gọi đến EasyTracker.getTracker():

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

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

Thay thế tất cả phương thức tiện lợi send<hit-type> bằng phương thức send(Map<String, String> parameters) mới:

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

Tìm hiểu thêm về cách gửi dữ liệu trong phiên bản 3.

Thay thế tham số EasyTracker ga_debug bằng ga_logLevel và một trong các giá trị độ chi tiết sau: 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>

Xem Tài liệu tham khảo về EasyTracker để biết thêm chi tiết.

Ngừng sử dụng GoogleAnalytics.requestAppOptOut(). Thay vào đó, hãy sử dụng 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();
```
Thận trọng: Trong phiên bản 3, SDK không duy trì chế độ cài đặt chọn không sử dụng ở cấp ứng dụng và phải đặt chế độ này mỗi khi chạy ứng dụng. Tìm hiểu thêm về cách thiết lập chế độ Chọn không tham gia ở cấp ứng dụng
(Không bắt buộc) Thêm tham số EasyTracker ga_dryRun và đặt thành true khi kiểm thử phương thức triển khai để ngăn dữ liệu kiểm thử xuất hiện trong báo cáo phát hành chính thức:

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

Triển khai tuỳ chỉnh: phiên bản 1.x đến phiên bản 3

Những người dùng phiên bản 1.x không sử dụng EasyTracker nên làm theo Hướng dẫn bắt đầu sử dụng phiên bản 3 và tham khảo Hướng dẫn cho nhà phát triển về Cấu hình nâng cao nếu cần.

Triển khai tuỳ chỉnh: phiên bản 2.x đến phiên bản 3

Những người dùng v2.x không sử dụng EasyTracker nên làm theo các bước bên dưới để hoàn tất việc nâng cấp lên v3:

Thay thế tất cả các phương thức tiện lợi "send<hit-type>" bằng phương thức send(Map<String, String> parameters) mới:

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

Xoá lệnh gọi đến GoogleAnalytics.setDebug(), thay thế bằng GoogleAnalytics.getLogger().setLogLevel():

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

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

Tìm hiểu thêm về Trình ghi nhật ký

SDK phiên bản 3 không còn tự động bắt đầu một phiên mới khi ứng dụng mở (ngoại trừ khi sử dụng EasyTracker). Nếu muốn duy trì hành vi này từ phương thức triển khai tuỳ chỉnh v2, bạn cần triển khai logic kiểm soát phiên của riêng mình khi người dùng khởi động ứng dụng:

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

(Không bắt buộc) Đặt cờ dryRun trong khi kiểm thử để ngăn không cho xử lý dữ liệu kiểm thử thông qua báo cáo phát hành công khai:

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

Tài liệu tham khảo

Các phần sau đây cung cấp ví dụ tham khảo về cách thiết lập và gửi dữ liệu bằng SDK V3.

Gửi dữ liệu bằng Maps trong phiên bản 3

Trong phiên bản 3, dữ liệu được gửi bằng một phương thức send() duy nhất. Phương thức này lấy một Map trường và giá trị trong Google Analytics làm đối số. Một lớp tiện ích MapBuilder được cung cấp để đơn giản hoá quá trình tạo lượt truy cập:

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

Bạn có thể sử dụng lớp MapBuilder để tạo bất kỳ loại lượt truy cập nào được hỗ trợ, chẳng hạn như sự kiện:

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

Tìm hiểu thêm về cách gửi dữ liệu trong phiên bản 3.

Cài đặt dữ liệu trên Công cụ theo dõi trong phiên bản 3

Bạn cũng có thể đặt các giá trị trực tiếp trên Tracker bằng phương thức set(). Các giá trị đã đặt trực tiếp được áp dụng cho tất cả các lượt truy cập tiếp theo từ 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()
);

Để xoá một giá trị đã được đặt trên Tracker, hãy đặt thuộc tính đó thành 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()
);

Tìm hiểu thêm về cách Thiết lập dữ liệu trong phiên bản 3