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 Thẻ Google Trình quản lý trong ứ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 của họ.

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 đến các thị trường ứng dụng.

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

• Nhiều chế độ cài đặt giao diện người dùng và chuỗi hiển thị
• 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

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, bật động như:

• Sử dụng kích thước màn hình để xác định kích thước biểu ngữ quảng cáo
• Sử dụng ngôn ngữ và vị trí để định cấu hình các phần tử 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 . 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 sự kiện nào sau đó thẻ hoặc pixel theo dõi.

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

Hoàn thành các bước sau trước khi bạn bắt đầu 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

Khi bạn đã hoàn tất các 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 của bạn.

Bắt đầu

Sau khi làm theo Hướng dẫn bắt đầu sử dụng 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 của bạn
• Nhận 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ã từ Cute Animals ứng dụng mẫu đi kèm với SDK Dịch vụ Google Play. Bạn có thể xem toàn bộ nguồn thông tin của dự án này bằng: <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:

1. Thiết lập SDK Dịch vụ Google Play.
2. Nếu bạn sử dụng IDE không phải Android Studio, hãy thêm các quyền sau vào phần Tệp AndroidManifest.xml:

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

3. Để bật InstallReferrerReceiver để gọi trình nhận Google Analytics để thiết lập 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 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 làm 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 đầu tiên ứng dụng của bạn. Mặc định vùng chứa sẽ ngừng được sử dụng ngay khi ứng dụng có thể truy xuất mộ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 bạn muốn tải xuống.
3. Nhấp vào nút Download (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 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 nó.
   2. Đổi tên tệp nhị phân của vùng chứa nếu cần. Mã này chỉ bao gồm chữ 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 các quy tắc hoặc thẻ, thay vào đó, bạn có thể chọn sử dụng một tệp JSON đơn giản.

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

Cách 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 để đưa ra yêu cầu tải một vùng chứa, trong đó chỉ định Mã vùng chứa trong Trình quản lý thẻ của Google cũng như vùng chứa mặc định của bạn . 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 thẻ Google Giao diện web của trình quản lý. Lệnh gọi đến loadContainerPreferNonDefault() không tuần tự 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 khi quảng cáo đã 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, vùng chứa sẽ đủ điều kiện để được làm mới qua mạng 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 bản sao của ContainerHolder cho mỗi lần chạy . Đó là lý do tại sao 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. Đây là những gì Lớp ContainerHolderSingleton sẽ 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ã từ Ứng dụng mẫu

Đoạn mã sau cho thấy mẫu đầy đủ được triển khai trong phương thức onCreate() của một 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 tải vùng chứa, bạn có thể truy xuất các giá trị cấu hình bằng cách sử dụng bất kỳ Container.get<type>() phương thức. Giá trị cấu hình được xác định bằng 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 ta đã quyết định sử dụng cho phần tử giao diện người dùng và trả về màu đó dưới dạng một 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 2 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), nơi bạn có xác định khoá và giá trị trong giao diện web của Trình quản lý thẻ của Google.

5. Đẩy 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ào đó về ứng dụng của bạn mà có thể được đọc ở các phần khác của ứng dụng hoặc được dùng để kích hoạt thẻ mà bạn đã thiết lập 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 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 lên dataLayer

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

Ví dụ: thay vì mã hoá cứng lượt xem màn hình Google Analytics theo dõi cuộc gọi vào ứng dụng của mình, bạn có thể đẩy các sự kiệ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. Điều này cho phép bạn linh hoạt sửa đổi thẻ đó hoặc thêm các thẻ bổ sung 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 của bạn.

Để đẩ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ã từ Ứng dụng mẫu

Lớp tiện ích sau đây minh hoạ cách đẩy sự kiện, chẳng hạn như thông tin về màn hình mở và đóng trong ứng dụng của bạn, 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 phiên bản vùng chứa, bạn sẽ muốn xem trước để đảm bảo phiên bản đó hoạt động như dự định. Trình quản lý thẻ của Google cho phép bạn xem trước các phiên bản vùng chứa của bạn bằng cách tạo các 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 ngoài dự kiến.

Đang xem trước

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

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

   <!--  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 để bao gồ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 vùng chứa Phiên bản để 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 được tạo hoặc Mã QR để chạy ứng dụng của bạn
4. Bạn có thể thoát khỏi chế độ xem trước bằng cách truy cập vào một đường liên kết do tính năng Tạo đường liên kết cuối xem trướ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à xác minh rằng vùng chứa đó hoạt động như dự kiến, bạn có thể xuất bản vùng chứa của bạn. Thông tin các giá trị cấu hình vùng chứa, thẻ và sự kiện sẽ được cung cấp cho người dùng vào lần tới đượ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ả các lựa chọn cấu hình nâng cao mà bạn muốn sử dụng để tuỳ chỉnh thêm 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 sau mỗi 12 giờ. Cách làm mới theo cách thủ công vùng chứa, hãy sử dụng ContainerHolder.refresh():

ContainerHolderSingleton.getContainerHolder().refresh();

Đây là lệnh gọi không đồng bộ và sẽ không trả về ngay lập tức. Để giảm lưu lượng truy cập mạng, refresh() có thể chỉ được gọi 15 phút một lần, nếu không thì dịch vụ 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 chạy ở trên.

Xem Đoạn mã từ Ứ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();
}