Android phiên bản 4 – Bắt đầu

Lưu ý: Hướng dẫn này mô tả cách triển khai cũ của Trình quản lý thẻ của Google trong các ứng dụng Android. Người dùng mới nên sử dụng Trình quản lý thẻ + Firebase để triển khai Trình quản lý thẻ của Google trong các ứng dụng Android.

Giới thiệu

Trình quản lý thẻ của Google cho phép nhà phát triển thay đổi giá trị cấu hình trong ứng dụng dành cho thiết bị di động của họ bằng cách sử dụng giao diện Trình quản lý thẻ của Google mà không phải tạo lại và gửi lại tệp nhị phân của ứng dụng cho chợ ứng dụng.

Việc này rất hữu ích để quản lý mọi giá trị hoặc cờ cấu hình trong ứng dụng mà bạn có thể cần thay đổi trong tương lai, bao gồm:

• Các chuỗi hiển thị và chế độ cài đặt giao diện người dùng khác nhau
• Kích thước, vị trí hoặc loại quảng cáo được phân phát trong ứng dụng của bạn
• Nhiều chế độ cài đặt cho trò chơi

Các giá trị cấu hình cũng có thể được đánh giá trong thời gian chạy bằng cách sử dụng các quy tắc, cho phép các cấu hình động như:

• Sử dụng kích thước màn hình để xác định kích thước biểu ngữ của quảng cáo
• Sử dụng ngôn ngữ và vị trí để định cấu hình các thành phần trên giao diện người dùng

Trình quản lý thẻ của Google cũng cho phép triển khai động các thẻ và pixel theo dõi trong các ứng dụng. Nhà phát triển có thể đẩy các sự kiện quan trọng vào một lớp dữ liệu và quyết định sau đó nên kích hoạt thẻ theo dõi hoặc pixel nào.

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

Hãy hoàn tất các bước sau trước khi bắt đầu sử dụng hướng dẫn bắt đầu này:

• Cài đặt SDK Android
• Tải SDK Dịch vụ Google Play xuống
• Tạo tài khoản Trình quản lý thẻ của Google
• Định cấu hình vùng chứa Trình quản lý thẻ của Google

Sau khi hoàn tất những bước này, phần còn lại của hướng dẫn này sẽ hướng dẫn bạn cách định cấu hình và sử dụng Trình quản lý thẻ của Google trong ứng dụng Android.

Bắt đầu

Sau khi làm theo hướng dẫn Bắt đầu này, bạn sẽ hiểu cách:

• Thêm Trình quản lý thẻ của Google vào dự án
• Khởi chạy Trình quản lý thẻ trong ứng dụng
• Nhận các giá trị cấu hình từ vùng chứa Trình quản lý thẻ
• Đẩy các giá trị và sự kiện vào dataLayer
• Xem trước, gỡ lỗi và xuất bản vùng chứa

Hướng dẫn này sử dụng các đoạn mã của ứng dụng mẫu Cute Animals có trong SDK Dịch vụ Google Play. Nguồn hoàn chỉnh của dự án này có trong: <android-sdk-directory>/extras/google/google_play_services/tagmanager/cuteanimals.

1. Thêm Trình quản lý thẻ của Google vào Dự án

Cách thêm Trình quản lý thẻ của Google vào dự án của bạn:

1. Thiết lập SDK Dịch vụ Google Play.
2. Nếu bạn dùng một IDE khác Android Studio, hãy thêm các quyền sau đây vào tệp AndroidManifest.xml:

   <!-- For TagManager SDK -->
   <uses-permission android:name="android.permission.INTERNET" />
   <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
   

3. Để cho phép InstallReferrerReceiver gọi trình nhận Google Analytics nhằm đặt dữ liệu chiến dịch, hãy thêm đoạn mã sau vào tệp AndroidManifest.xml:

   <!-- Used for install referrer tracking-->
   <service android:name="com.google.android.gms.tagmanager.InstallReferrerService" />
   <receiver
     android:name="com.google.android.gms.tagmanager.InstallReferrerReceiver"
     android:exported="true">
     <intent-filter>
       <action android:name="com.android.vending.INSTALL_REFERRER" />
     </intent-filter>
   </receiver>
   

2. Thêm một tệp vùng chứa mặc định vào dự án

Lưu ý: Nếu bạn chưa định cấu hình vùng chứa trong giao diện web của Trình quản lý thẻ của Google, hãy quay lại bước này sau khi thực hiện xong.

Trình quản lý thẻ của Google sử dụng vùng chứa mặc định trong lần chạy ứng dụng đầu tiên của bạn. Vùng chứa mặc định sẽ ngừng được sử dụng ngay khi ứng dụng có thể truy xuất vùng chứa mới qua mạng.

Cách tải xuống và thêm tệp nhị phân của vùng chứa mặc định vào ứng dụng:

1. Đăng nhập vào giao diện web của Trình quản lý thẻ của Google.
2. Chọn Phiên bản của vùng chứa mà bạn muốn tải xuống.
3. Nhấp vào nút Tải xuống để truy xuất tệp nhị phân của vùng chứa.
4. Thêm tệp nhị phân của vùng chứa đã tải xuống vào dự án của bạn dưới dạng tài nguyên thô.
   1. Nếu thư mục con raw trong <project-root>/res/ không tồn tại, hãy tạo thư mục con đó.
   2. Đổi tên tệp nhị phân của vùng chứa nếu cần. Mã này chỉ chứa chữ cái viết thường, chữ số và dấu gạch dưới.
   3. Sao chép tệp nhị phân của vùng chứa vào thư mục <project-root>/res/raw.

Mặc dù bạn nên sử dụng tệp nhị phân, nhưng nếu vùng chứa của bạn không chứa quy tắc hoặc thẻ, bạn có thể chọn dùng một tệp JSON đơn giản.

3. Khởi chạy Trình quản lý thẻ của Google

Để khởi chạy Trình quản lý thẻ của Google trong ứng dụng của bạn:

1. Tải singleton TagManager:

   TagManager tagManager = TagManager.getInstance(this);
   

2. Sử dụng singleton TagManager để yêu cầu tải một vùng chứa, chỉ định mã vùng chứa trong Trình quản lý thẻ của Google cũng như tệp vùng chứa mặc định. Mã vùng chứa phải được viết hoa và khớp chính xác với mã vùng chứa trong giao diện web của Trình quản lý thẻ của Google. Lệnh gọi đến loadContainerPreferNonDefault() không chặn và trả về một PendingResult:

   PendingResult<ContainerHolder> pending =
           tagManager.loadContainerPreferNonDefault(CONTAINER_ID,
           R.raw.defaultcontainer_binary);
   

3. Sử dụng ResultCallback để trả về ContainerHolder sau khi tải xong hoặc hết thời gian chờ:

   // The onResult method will be called as soon as one of the following happens:
   //     1. a saved container is loaded
   //     2. if there is no saved container, a network container is loaded
   //     3. the 2-second timeout occurs
   pending.setResultCallback(new ResultCallback<ContainerHolder>() {
       @Override
       public void onResult(ContainerHolder containerHolder) {
           ContainerHolderSingleton.setContainerHolder(containerHolder);
           Container container = containerHolder.getContainer();
           if (!containerHolder.getStatus().isSuccess()) {
               Log.e("CuteAnimals", "failure loading container");
               displayErrorToUser(R.string.load_error);
               return;
           }
           ContainerLoadedCallback.registerCallbacksForContainer(container);
           containerHolder.setContainerAvailableListener(new ContainerLoadedCallback());
           startMainActivity();
       }
   }, TIMEOUT_FOR_CONTAINER_OPEN_MILLISECONDS, TimeUnit.MILLISECONDS);
   

   Lưu ý: Theo mặc định, một vùng chứa sẽ đủ điều kiện được làm mới qua mạng sau mỗi 12 giờ. Tìm hiểu cách làm mới vùng chứa theo cách thủ công.

   Tạo một ContainerHolder Singleton

   Bạn chỉ nên duy trì một thực thể của ContainerHolder trong mỗi lần chạy ứng dụng. Đó là lý do ví dụ trên sử dụng lớp tiện ích ContainerHolderSingleton để quản lý quyền truy cập vào thực thể ContainerHolder. Lớp ContainerHolderSingleton đó có dạng như sau:

   package com.google.android.tagmanager.examples.cuteanimals;
   
   import com.google.android.gms.tagmanager.ContainerHolder;
   
   /**
    * Singleton to hold the GTM Container (since it should be only created once
    * per run of the app).
    */
   public class ContainerHolderSingleton {
       private static ContainerHolder containerHolder;
   
       /**
        * Utility class; don't instantiate.
        */
       private ContainerHolderSingleton() {
       }
   
       public static ContainerHolder getContainerHolder() {
           return containerHolder;
       }
   
       public static void setContainerHolder(ContainerHolder c) {
           containerHolder = c;
       }
   }
   
   

Xem Đoạn mã trong Ứng dụng mẫu

Đoạn mã sau đây cho thấy mẫu đầy đủ được triển khai trong phương thức onCreate() của Activity mẫu:

package com.google.android.tagmanager.examples.cuteanimals;

import java.util.concurrent.TimeUnit;
import java.util.Map;

import android.app.Activity;
import android.app.AlertDialog;
import android.content.DialogInterface;
import android.content.Intent;
import android.os.Bundle;
import android.util.Log;

import com.google.android.gms.common.api.PendingResult;
import com.google.android.gms.common.api.ResultCallback;
import com.google.android.gms.tagmanager.Container;
import com.google.android.gms.tagmanager.Container.FunctionCallMacroCallback;
import com.google.android.gms.tagmanager.Container.FunctionCallTagCallback;
import com.google.android.gms.tagmanager.ContainerHolder;
import com.google.android.gms.tagmanager.TagManager;

/**
 * Displays simple splash screen while GTM container is loading. Once the container is loaded,
 * launches the {@link MainActivity}.
 */
public class SplashScreenActivity extends Activity {
    private static final long TIMEOUT_FOR_CONTAINER_OPEN_MILLISECONDS = 2000;
    private static final String CONTAINER_ID = "GTM-XXXX";

    @Override
    public void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_splashscreen);

        TagManager tagManager = TagManager.getInstance(this);

        // Modify the log level of the logger to print out not only
        // warning and error messages, but also verbose, debug, info messages.
        tagManager.setVerboseLoggingEnabled(true);

        PendingResult<ContainerHolder> pending =
                tagManager.loadContainerPreferNonDefault(CONTAINER_ID,
                R.raw.defaultcontainer_binary);

        // The onResult method will be called as soon as one of the following happens:
        //     1. a saved container is loaded
        //     2. if there is no saved container, a network container is loaded
        //     3. the 2-second timeout occurs
        pending.setResultCallback(new ResultCallback<ContainerHolder>() {
            @Override
            public void onResult(ContainerHolder containerHolder) {
                ContainerHolderSingleton.setContainerHolder(containerHolder);
                Container container = containerHolder.getContainer();
                if (!containerHolder.getStatus().isSuccess()) {
                    Log.e("CuteAnimals", "failure loading container");
                    displayErrorToUser(R.string.load_error);
                    return;
                }
                ContainerLoadedCallback.registerCallbacksForContainer(container);
                containerHolder.setContainerAvailableListener(new ContainerLoadedCallback());
                startMainActivity();
            }
        }, TIMEOUT_FOR_CONTAINER_OPEN_MILLISECONDS, TimeUnit.MILLISECONDS);
  // Rest of the Activity definition.
}

4. Nhận giá trị cấu hình từ vùng chứa

Sau khi vùng chứa được tải, bạn có thể truy xuất các giá trị cấu hình bằng bất kỳ phương thức Container.get<type>() nào. Giá trị cấu hình được xác định bằng các biến thu thập giá trị trong Trình quản lý thẻ của Google. Ví dụ: phương thức sau truy xuất màu mới nhất mà chúng tôi quyết định sử dụng cho một thành phần trên giao diện người dùng và trả về màu đó dưới dạng số nguyên:

/**
 * Returns an integer representing a color.
 */
private int getColor(String key) {
    return colorFromColorName(containerHolder.getContainer().getString(key));
}

Mã này thực hiện hai việc để truy xuất tên màu từ vùng chứa:

1. Lấy Container từ ContainerHolder bằng cách sử dụng ContainerHolder.getContainer().
2. Lấy giá trị màu bằng cách sử dụng Container.getString(key), trong đó bạn đã xác định khoá và giá trị trong giao diện web của Trình quản lý thẻ của Google.

5. Đưa các sự kiện và giá trị vào dataLayer

Trình quản lý thẻ của Google cũng cung cấp dataLayer để bạn có thể đẩy thông tin về ứng dụng có thể đọc được trong các phần khác của ứng dụng hoặc dùng để kích hoạt các thẻ mà bạn đã định cấu hình trong giao diện web của Trình quản lý thẻ của Google.

Đẩy các giá trị vào dataLayer

dataLayer cung cấp một lớp dữ liệu cố định mà bạn có thể dùng để lưu trữ các cặp khoá-giá trị mà bạn có thể muốn sử dụng trong các phần khác của ứng dụng, hoặc làm dữ liệu đầu vào cho thẻ Trình quản lý thẻ của Google.

Để đẩy một giá trị đến dataLayer, hãy làm theo mẫu sau:

1. Tải singleton DataLayer:

   DataLayer dataLayer = TagManager.getInstance(context).getDataLayer();
   

2. Đẩy sự kiện bằng DataLayer.push():

   // Put the image_name into the data layer for future use.
   TagManager.getInstance(this).getDataLayer().push(IMAGE_NAME_KEY, imageName);
   

Để nhận giá trị từ dataLayer, hãy sử dụng DataLayer.get(key).

Đẩy sự kiện vào dataLayer

Việc đẩy sự kiện đến dataLayer cho phép bạn tách mã xử lý ứng dụng khỏi các thẻ mà bạn có thể muốn kích hoạt để phản hồi những sự kiện đó.

Ví dụ: thay vì mã hoá cứng các lệnh gọi theo dõi lượt xem màn hình Google Analytics vào ứng dụng, bạn có thể đẩy các sự kiện trên màn hình vào dataLayer và xác định các thẻ theo dõi thông qua giao diện web của Trình quản lý thẻ của Google. Nhờ đó, bạn có thể linh hoạt sửa đổi thẻ đó hoặc thêm các thẻ khác phản hồi các sự kiện trên màn hình mà không cần cập nhật mã xử lý ứng dụng.

Để đẩy một sự kiện đến dataLayer, hãy làm theo mẫu sau:

1. Tải singleton DataLayer:

   DataLayer dataLayer = TagManager.getInstance(context).getDataLayer();
   

2. Đẩy sự kiện bằng DataLayer.pushEvent():

   dataLayer.pushEvent("openScreen", DataLayer.mapOf("screenName", screenName));
   

   DataLayer.mapOf() là một phương thức tiện ích mà bạn có thể sử dụng để dễ dàng tạo bản đồ các cặp khoá-giá trị sẽ cập nhật dataLayer cùng lúc với sự kiện được đẩy.

Xem Đoạn mã trong Ứng dụng mẫu

Lớp tiện ích sau đây minh hoạ cách đẩy các sự kiện (chẳng hạn như thông tin về màn hình mở và đóng trong ứng dụng) trên dataLayer:

package com.google.android.tagmanager.examples.cuteanimals;

import android.content.Context;

import com.google.android.gms.tagmanager.DataLayer;
import com.google.android.gms.tagmanager.TagManager;

/**
 * Utility class.
 */
public class Utils {
    private Utils() {
        // private constructor.
    }

    /**
     * Push an "openScreen" event with the given screen name. Tags that match that event will fire.
     */
    public static void pushOpenScreenEvent(Context context, String screenName) {
        DataLayer dataLayer = TagManager.getInstance(context).getDataLayer();
        dataLayer.pushEvent("openScreen", DataLayer.mapOf("screenName", screenName));
    }

    /**
     * Push a "closeScreen" event with the given screen name. Tags that match that event will fire.
     */
    public static void pushCloseScreenEvent(Context context, String screenName) {
        DataLayer dataLayer = TagManager.getInstance(context).getDataLayer();
        dataLayer.pushEvent("closeScreen", DataLayer.mapOf("screenName", screenName));
    }
}

6. Xem trước, gỡ lỗi và xuất bản

Trước khi xuất bản một phiên bản vùng chứa, bạn nên xem trước phiên bản đó để đảm bảo phiên bản đó hoạt động như dự kiến. Trình quản lý thẻ của Google giúp bạn có thể xem trước các phiên bản của vùng chứa bằng cách tạo đường liên kết và mã QR trong giao diện web rồi sử dụng chúng để mở ứng dụng của bạn. Bạn cũng có thể bật chế độ ghi nhật ký chi tiết để gỡ lỗi mọi hành vi không mong muốn.

Đang xem trước

Để xem trước phiên bản vùng chứa của bạn, hãy làm theo các bước sau:

1. Đang thêm bản xem trước Activity này vào tệp AndroidManifest:

   <!--  Add preview activity. -->
   <activity
       android:name="com.google.android.gms.tagmanager.PreviewActivity"
       android:label="@string/app_name"
       android:noHistory="true">  <!-- optional, removes the previewActivity from the activity stack. -->
       <intent-filter>
         <data android:scheme="tagmanager.c.com.google.android.tagmanager.examples.cuteanimals" />
         <action android:name="android.intent.action.VIEW" />
         <category android:name="android.intent.category.DEFAULT" />
         <category android:name="android.intent.category.BROWSABLE"/>
       </intent-filter>
   </activity>
   

   Hãy nhớ sửa đổi dòng này để thêm tên gói của ứng dụng:

   <data android:scheme="tagmanager.c.com.google.android.tagmanager.examples.cuteanimals" />
   

2. Tạo đường liên kết xem trước trong giao diện web của Trình quản lý thẻ của Google
   1. Đăng nhập vào Trình quản lý thẻ của Google
   2. Chọn Phiên bản của vùng chứa để xem trước
   3. Nhấp vào nút Xem trước
   4. Nhập tên gói của ứng dụng rồi nhấp vào Tạo đường liên kết bắt đầu xem trước
3. Sử dụng đường liên kết đã tạo hoặc mã QR để chạy ứng dụng
4. Bạn có thể thoát khỏi chế độ xem trước bằng cách truy cập vào đường liên kết do tuỳ chọn Generate end Preview link (Tạo đường liên kết tạo bản xem trước kết thúc) tạo trong giao diện web.

Gỡ lỗi

Nếu bạn cần khắc phục sự cố khi triển khai vùng chứa, hãy bật tính năng ghi nhật ký chi tiết bằng cách gọi TagManager.setVerboseLoggingEnabled(true):

// Modify the log level of the logger to print out not only
// warning and error messages, but also verbose, debug, info messages.
tagManager.setVerboseLoggingEnabled(true);

Xuất bản

Sau khi xem trước vùng chứa và xác minh rằng vùng chứa đó đang hoạt động như dự kiến, bạn có thể xuất bản vùng chứa của mình. Các giá trị cấu hình vùng chứa, thẻ và sự kiện của bạn sẽ hiển thị cho người dùng vào lần tiếp theo vùng chứa của họ được làm mới. Tìm hiểu thêm về cách làm mới vùng chứa.

Cấu hình nâng cao

Các phần sau đây mô tả những lựa chọn cấu hình nâng cao mà bạn muốn sử dụng để tuỳ chỉnh thêm hoạt động triển khai Trình quản lý thẻ của Google.

Làm mới vùng chứa

Theo mặc định, vùng chứa của bạn sẽ đủ điều kiện để được làm mới mỗi 12 giờ. Để làm mới vùng chứa theo cách thủ công, hãy sử dụng ContainerHolder.refresh():

ContainerHolderSingleton.getContainerHolder().refresh();

Đây là lệnh gọi không đồng bộ sẽ không trả về ngay lập tức. Để giảm lưu lượng truy cập mạng, refresh() chỉ có thể được gọi 15 phút một lần, nếu không, refresh() sẽ không hoạt động.

Lưu ý: Đoạn mã này sử dụng lớp tiện ích ContainerHolderSingleton được mô tả trong ví dụ khởi động ở trên.

Xem Đoạn mã trong Ứng dụng mẫu

public void refreshButtonClicked(@SuppressWarnings("unused") View view) {
    Log.i(TAG, "refreshButtonClicked");
    ContainerHolderSingleton.getContainerHolder().refresh();

    // Push the "refresh" event to trigger firing an analytics tag.
    TagManager.getInstance(this).getDataLayer().push("event", "refresh");
    // Push the "custom tag" event to trigger firing a custom function call tag.
    TagManager.getInstance(this).getDataLayer().push("event", "custom_tag");
    updateCategories();
}