Android v4 - 開始使用

簡介

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

這有助於管理應用程式中可能需要變更的任何設定值或標記，包括：

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

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

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

此外，Google 代碼管理工具也能在應用程式中動態導入追蹤代碼和像素。開發人員可以將重要事件推送到資料層，稍後再決定要觸發哪些追蹤代碼或像素。

事前準備

在開始本指南之前，請先完成下列步驟：

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

入門課程

看完這份入門指南後，您會瞭解如何：

本指南採用 Google Play 服務 SDK 內含的 Cute Animals 範例應用程式程式碼片段。 本專案的完整來源可在 <android-sdk-directory>/extras/google/google_play_services/tagmanager/cuteanimals 中找到。

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

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

  1. 設定 Google Play 服務 SDK。
  2. 如果您使用的 IDE 並非 Android Studio，請在 AndroidManifest.xml 檔案中加入下列權限：
    <!-- For TagManager SDK -->
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
  3. 如要讓 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 代碼管理工具會在首次執行應用程式時使用預設容器。一旦應用程式能夠透過網路擷取新的容器，預設容器就會停止運作。

如要下載預設容器二進位檔並新增至應用程式，請按照下列步驟操作：

  1. 登入 Google 代碼管理工具網頁介面。
  2. 選取要下載的容器「版本」。
  3. 點選「下載」按鈕即可擷取容器二進位檔。
  4. 將下載的容器二進位檔案新增至專案，做為原始資源。
    1. 如果 <project-root>/res/ 下的 raw 子資料夾不存在，請建立該子資料夾。
    2. 如有必要，請重新命名容器二進位檔案。只能由小寫英文字母、數字和底線組成。
    3. 將容器二進位檔案複製到 <project-root>/res/raw 資料夾。

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

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

如要在應用程式中初始化 Google 代碼管理工具：

  1. 取得 TagManager 單例模式：
    TagManager tagManager = TagManager.getInstance(this);
  2. 使用 TagManager 單例模式提出載入容器的要求，並指定 Google 代碼管理工具容器 ID 和預設容器檔案。容器 ID 應大寫，且與 Google 代碼管理工具網頁介面中的容器 ID 完全相符。對 loadContainerPreferNonDefault() 的呼叫屬於非阻塞式情況，並會傳回 PendingResult：
    PendingResult<ContainerHolder> pending =
        tagManager.loadContainerPreferNonDefault(CONTAINER_ID,
        R.raw.defaultcontainer_binary);
  3. 在 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 Singleton

    每次執行應用程式都應只保留一個 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;
    }
}

4. 從容器取得設定值

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

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

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

  1. 使用 ContainerHolder.getContainer() 從 ContainerHolder 取得 Container。
  2. 使用 Container.getString(key) 取得顏色值，您可以在 Google 代碼管理工具網頁介面中定義鍵和值。

5. 將事件和值推送到 dataLayer

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

將值推送到 dataLayer

dataLayer 提供層層持續性，可讓您用來儲存要在應用程式其他部分中使用的鍵/值組合，或做為 Google 代碼管理工具代碼的輸入內容。

如要將值推送至 dataLayer，請遵循以下模式：

  1. 取得 DataLayer 單例模式：
    DataLayer dataLayer = TagManager.getInstance(context).getDataLayer();
  2. 使用 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 後，您就能將應用程式程式碼與自己想要觸發的標記來回應這些事件的標記分開。

舉例來說，您可以將畫面事件推送至 dataLayer，並透過 Google 代碼管理工具網頁介面定義追蹤代碼，而不需將 Google Analytics (分析) 畫面瀏覽追蹤呼叫硬式編碼。這樣一來，您完全不必更新應用程式程式碼，就能修改該代碼，或是新增其他代碼來回應畫面事件。

如要將事件推送至 dataLayer，請遵循以下模式：

  1. 取得 DataLayer 單例模式：
    DataLayer dataLayer = TagManager.getInstance(context).getDataLayer();
  2. 使用 DataLayer.pushEvent() 推送事件：
    dataLayer.pushEvent("openScreen", DataLayer.mapOf("screenName", screenName));

    DataLayer.mapOf() 是一種公用程式方法，可輕鬆產生鍵/值組合的對應，在推送事件時更新 dataLayer。

6. 預覽、偵錯和發布

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

預覽中

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

  1. 在 AndroidManifest 檔案中新增這個預覽畫面 Activity： 
    <!--  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" />
  2. 在 Google 代碼管理工具網頁介面中產生預覽連結
    1. 登入 Google 代碼管理工具
    2. 選取要預覽的容器「版本」
    3. 按一下 [預覽] 按鈕
    4. 輸入應用程式的套件名稱，然後按一下「產生開始預覽連結」。
  3. 請使用產生的連結或 QR code 啟動應用程式
  4. 如要退出預覽模式，請點選網頁介面中的「產生結束預覽連結」選項所產生的連結。

偵錯

如果您需要排解容器實作問題，請呼叫 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() 可能每 15 分鐘才會呼叫一次，否則就無需人工管理。