本頁面由 Cloud Translation API 翻譯而成。

Android v4 - 開始使用

簡介

Google 代碼管理工具可讓開發人員更改行動應用程式中的設定值使用 Google 代碼管理工具介面，不必重建並重新提交應用程式二進位檔應用程式市集

如要在應用程式中管理任何您需要的設定值或標記，這項功能就能派上用場，包括：

各種 UI 設定和顯示字串
在應用程式中放送的廣告大小、位置或類型
各種遊戲設定

您也可以在執行階段使用規則評估設定值，啟用動態調整設定如下：

使用螢幕大小決定廣告橫幅大小
使用語言和位置設定 UI 元素

Google 代碼管理工具也能動態導入追蹤代碼和像素的應用程式。開發人員可以將重要事件推送至資料層，然後決定追蹤像素或像素必須觸發。

事前準備

在開始這份入門指南之前，請先完成下列步驟：

完成上述步驟後，本指南的其餘部分將逐步說明如何在您的 Android 應用程式中設定及使用 Google 代碼管理工具。

開始使用

讀完這份入門指南後，您就能瞭解如何：

在專案中加入 Google 代碼管理工具
在應用程式中初始化代碼管理工具
從代碼管理工具容器取得設定值
將值和事件推送至 dataLayer
預覽、偵錯及發布容器

本指南使用 Cute Animals 的程式碼片段應用程式範例 Google Play 服務 SDK。這項專案的完整來源位於：<android-sdk-directory>/extras/google/google_play_services/tagmanager/cuteanimals。

1. 在專案中加入 Google 代碼管理工具

如要在專案中加入 Google 代碼管理工具，請按照下列步驟操作：

設定 Google Play 服務 SDK。

如果您使用以外的 IDE Android Studio，將下列權限新增至 AndroidManifest.xml 檔案：

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

啟用 InstallReferrerReceiver，以便呼叫 Google Analytics 接收器設定廣告活動資料，請在 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. 在專案中新增預設容器檔案

Google 代碼管理工具會在應用程式第一次執行時使用預設容器。預設只要應用程式能在更是如此

下載預設容器二進位檔並加入應用程式：

登入 Google 代碼管理工具網頁介面。
選取要下載的容器「版本」。
點選「下載」按鈕，擷取容器二進位檔。
將下載的容器二進位檔案加入專案中，做為原始資源。
1. 如果找到的 raw 子資料夾 <project-root>/res/ 不存在，請建立該項目。
2. 視需要重新命名容器二進位檔案。其中包含小寫英文字母、數字和底線。
3. 將容器二進位檔檔案複製到資料夾 <project-root>/res/raw。

雖然我們建議您使用二進位檔案，但如果容器不含規則或標記，可以選擇改用簡單的 JSON 檔案

3. 正在初始化 Google 代碼管理工具

如要在應用程式中初始化 Google 代碼管理工具，請按照下列步驟操作：

取得 TagManager 單例模式：

TagManager tagManager = TagManager.getInstance(this);

使用 TagManager 單例模式發出載入容器的要求，並指定 Google 代碼管理工具容器 ID 和預設容器檔案。容器 ID 應該是大寫，並且與 Google 代碼中的容器 ID 完全相符 Manager 網頁介面。對 loadContainerPreferNonDefault() 的呼叫屬於非封鎖性質然後傳回 PendingResult:
```
PendingResult<ContainerHolder> pending =
        tagManager.loadContainerPreferNonDefault(CONTAINER_ID,
        R.raw.defaultcontainer_binary);
```

使用 ResultCallback 則可傳回 ContainerHolder。載入完成或逾時時：

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

敬上

建立 ContainerHolder 單例模式

每次執行ContainerHolder 應用程式。因此，上述範例使用 ContainerHolderSingleton 公用程式類別的原因。可以管理 ContainerHolder 執行個體的存取權。這就是這個 ContainerHolderSingleton 類別如下所示：

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

查看範例應用程式的程式碼片段

下列程式碼片段會顯示在 Activity 範例的 onCreate() 方法中實作的完整模式：

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. 從容器取得設定值

載入容器後，您可以使用 Container.get<type>() 方法。設定值是使用 Google 代碼管理工具的值收集變數。舉例來說，如果擷取我們決定用於 UI 元素的最新顏色，然後傳回整數：

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

以下程式碼會執行兩項操作，從容器擷取顏色名稱：

使用以下程式碼從 ContainerHolder 取得 Container ContainerHolder.getContainer()。
使用以下程式碼取得色彩值： Container.getString(key)，其中在 Google 代碼管理工具網頁介面中定義鍵和值。

5. 將事件和值推送到 dataLayer

Google 代碼管理工具也提供 dataLayer，可用來推送資訊可在應用程式的其他部分讀取，或用來觸發代碼您在 Google 代碼管理工具網頁介面中設定的變更。

將值推送到 dataLayer

dataLayer 提供持續性層，可用於儲存您想在應用程式其他部分使用的鍵/值組合輸入至 Google 代碼管理工具代碼

如要將值推送至 dataLayer，請按照以下模式操作：

取得 DataLayer 單例模式：

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

使用推送事件 DataLayer.push()：

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

如要從 dataLayer 取得值，請使用 DataLayer.get(key)。

將事件推送至 dataLayer

只要將事件推送至 dataLayer，您就可以區隔應用程式程式碼協助您因應這些事件而觸發的代碼

舉例來說，您不必將 Google Analytics 畫面瀏覽追蹤呼叫寫入應用程式，您可以將畫面事件推送至 dataLayer，並透過 Google 代碼管理工具網頁介面。這樣您就能靈活地修改或新增其他標記，用來回應畫面事件，而不必更新應用程式程式碼。

如要將事件推送至 dataLayer，請按照以下模式操作：

取得 DataLayer 單例模式：

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

使用推送事件 DataLayer.pushEvent()：
```
dataLayer.pushEvent("openScreen", DataLayer.mapOf("screenName", screenName));
```
DataLayer.mapOf()是一種公用程式方法，可以輕鬆產生會在推送事件時更新 dataLayer 的鍵/值組合。

查看範例應用程式的程式碼片段

下列公用程式類別示範如何推送事件 (例如畫面相關資訊) 在應用程式中開啟和關閉 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. 預覽、偵錯和發布

建議您先預覽容器版本，確定容器可正常運作再發布正常運作。您可以使用 Google 代碼管理工具預覽，方法是在網頁介面中產生連結和 QR code，然後用來開啟應用程式。此外，您也可以啟用詳細記錄模式，對任何非預期的行為進行偵錯。

預覽中

如要預覽容器版本，請按照下列步驟操作：

將此預覽 Activity 新增到您的 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>

請務必修改這一行，加入應用程式的套件名稱：

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

在 Google 代碼管理工具網頁介面中產生預覽連結
1. 登入 Google 代碼管理工具
2. 選取要預覽的容器「版本」
3. 按一下 [預覽] 按鈕
4. 輸入應用程式的套件名稱，然後按一下「產生開始預覽連結」
使用系統產生的連結或 QR code 啟動應用程式
如要退出預覽模式，請點選「產生結束預覽連結」所產生的連結選項。

偵錯

如果您需要解決容器導入問題，請呼叫 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);

發布中

預覽容器並確認運作正常後發布容器。您的容器設定值、代碼和事件就會在使用者下次重新整理進一步瞭解如何重新整理容器。

進階設定

以下各節說明您想使用的進階設定選項，進一步自訂 Google 代碼管理工具導入。

重新整理容器

根據預設，容器可以每 12 小時更新一次。手動重新整理容器中，使用 ContainerHolder.refresh()：

ContainerHolderSingleton.getContainerHolder().refresh();

此為非同步呼叫，不會立即傳回。為了減少網路流量，refresh() 可系統只會呼叫一次

查看範例應用程式的程式碼片段

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