本開發人員指南說明如何在 行動應用程式
簡介
Google 代碼管理工具可讓開發人員變更設定 透過 Google 代碼管理工具 在行動應用程式中放送 不必重新建立應用程式二進位檔並重新提交至應用程式介面 市集。
這很適合用來管理任何設定值 日後可能需要變更 包括：
- 各種 UI 設定和顯示字串
- 在應用程式中放送的廣告大小、位置或類型
- 遊戲設定
您也能在執行階段使用規則，評估設定值 可啟用動態設定，例如：
- 使用螢幕大小決定廣告橫幅大小
- 使用語言和位置設定 UI 元素
Google 代碼管理工具也能以動態方式導入追蹤代碼 模型和像素的應用方式開發人員可以將重要事件推送至資料層，並稍後決定要觸發哪些追蹤代碼或像素。TagManager 目前支援下列代碼：
- Google 行動應用程式分析
- 自訂函式呼叫代碼
事前準備
使用這份入門指南之前，您必須符合以下條件：
- Google 代碼管理工具帳戶
- 全新的代碼管理工具 容器和值組合巨集
- 適用於導入 Google 代碼管理工具的 Android 行動應用程式
- Google Analytics 服務 SDK，其中包含代碼管理工具程式庫。
如果您是 Google 代碼管理工具新手，建議您 請先進一步瞭解容器、巨集和規則 (說明中心)，再繼續閱讀本指南。
開始使用
本節將引導開發人員完成一般的代碼管理工具工作流程：
1. 將 Google 代碼管理工具 SDK 加進專案
使用 Google 代碼管理工具 SDK 前，請務必先將 SDK 套件解壓縮
將程式庫新增至專案的建構路徑，並新增權限
新增到 AndroidManifest.xml 檔案中。
首先，請將 Google 代碼管理工具程式庫加進以下位置的 /libs 資料夾：
。
接著，請更新 AndroidManifest.xml 檔案，以便使用下列功能 權限：
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" /> <uses-permission android:name="android.permission.INTERNET" />
2. 在專案中新增預設容器檔案
Google 代碼管理工具會在應用程式第一次執行時使用預設容器。預設 並持續使用直到應用程式能透過 更是如此
如要下載及新增預設容器二進位檔至應用程式，請按照下列步驟操作：
- 登入 Google 代碼管理工具網頁介面。
- 選取要下載的容器「版本」。
- 點選「下載」按鈕，擷取容器二進位檔。
- 將二進位檔案加入
下列路徑：
<project-root>/assets/tagmanager/
預設檔案名稱應為容器 ID (例如 GTM-1234)。
已下載二進位檔案，請務必移除檔案名稱中的版本後置字串
以確保遵循正確的命名慣例
雖然我們建議您使用二進位檔案，但如果容器不含規則或標記，
可以選用一個簡單的
JSON
檔案。
檔案必須位於新的 /assets/tagmanager
資料夾，命名時應遵循以下命名慣例：
<Container_ID>.json。舉例來說
是 GTM-1234，請將預設容器值新增至
/assets/tagmanager/GTM-1234.json。
3. 開啟容器
從容器擷取值之前，應用程式必須先開啟 開啟容器時，系統會從磁碟載入容器 (如果有的話)。 (如有需要)，則會向網路發出要求。
如要在 Android 中開啟容器，最簡單的方法是使用
ContainerOpener.openContainer(..., Notifier notifier)，如以下範例所示：
import com.google.tagmanager.Container;
import com.google.tagmanager.ContainerOpener;
import com.google.tagmanager.ContainerOpener.OpenType;
import com.google.tagmanager.TagManager;
import android.app.Activity;
import android.os.Bundle;
public class RacingGame {
// Add your public container ID.
private static final String CONTAINER_ID = "GTM-YYYY";
volatile private Container mContainer;
@Override
public void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
TagManager mTagManager = TagManager.getInstance(this);
// The container is returned to containerFuture when available.
ContainerOpener.openContainer(
mTagManager, // TagManager instance.
CONTAINER_ID, // Tag Manager Container ID.
OpenType.PREFER_NON_DEFAULT, // Prefer not to get the default container, but stale is OK.
null, // Time to wait for saved container to load (ms). Default is 2000ms.
new ContainerOpener.Notifier() { // Called when container loads.
@Override
public void containerAvailable(Container container) {
// Handle assignment in callback to avoid blocking main thread.
mContainer = container;
}
}
);
// Rest of your onCreate code.
}
}
在本例中，ContainerOpener.openContainer(..., Notifier notifier) 的用途是
要求從本機儲存空間儲存容器透過處理
containerAvailable 回呼中的 mContainer，我們會確保
系統未封鎖主執行緒。如果儲存的容器存在超過 12 小時，
呼叫也會排程以非同步擷取最新容器的要求
您可以透過網路
這個實作範例代表以最簡便的方式開啟及擷取
透過 ContainerOpener 便利類別從容器擷取值。
如要進一步瞭解進階導入選項，請參閱進階設定。
4. 從容器取得設定值
容器開啟後，即可使用
get<type>Value()
方法：
// Retrieving a configuration value from a Tag Manager Container.
// Get the configuration value by key.
String title = mContainer.getStringValue("title_string");
以不存在的金鑰發出的要求，會傳回適當的預設值 改為要求類型：
// Empty keys will return a default value depending on the type requested.
// Key does not exist. An empty string is returned.
string subtitle = container.getStringValue("Non-existent-key");
subtitle.equals(""); // Evaluates to true.
5. 將值推送到 DataLayer
DataLayer 是一種地圖，可用來啟用應用程式的執行階段資訊，例如觸控功能 才能供代碼管理工具巨集和畫面瀏覽 都會在 Docker 容器中執行
例如，將畫面瀏覽的相關資訊推送到 DataLayer 地圖。 在代碼管理工具的網頁介面中設定代碼來觸發轉換像素 及追蹤來電以回應這些畫面瀏覽， 加入應用程式中
系統會使用 push() 和
DataLayer.mapOf() 輔助方法：
//
// MainActivity.java
// Pushing an openScreen event with a screen name into the data layer.
//
import com.google.tagmanager.TagManager;
import com.google.tagmanager.DataLayer;
import android.app.Activity;
import android.os.Bundle;
public MainActivity extends Activity {
public void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
}
// This screen becomes visible when Activity.onStart() is called.
public void onStart() {
super.onStart();
// The container should have already been opened, otherwise events pushed to
// the DataLayer will not fire tags in that container.
DataLayer dataLayer = TagManager.getInstance(this).getDataLayer();
dataLayer.push(DataLayer.mapOf("event",
"openScreen", // The event type. This value should be used consistently for similar event types.
"screenName", // Writes a key "screenName" to the dataLayer map.
"Home Screen") // Writes a value "Home Screen" for the "screenName" key.
);
}
// Rest of the Activity implementation
}
您現在可以在網頁介面中建立代碼 (例如 Google Analytics 代碼) 即可為每個畫面瀏覽觸發一個事件 等於「openScreen」。如何傳遞畫面名稱 加入其中一個標記，請建立參照「screenName」的資料層巨集 索引鍵的值您也可以建立 (例如 Google Ads 轉換像素) 只針對特定畫面瀏覽觸發，計算方式為 建立一個規則，其中 等於「openScreen」 && 等於「ConfirmationScreen」。
6. 預覽與發布容器
巨集值一律會與目前發布的版本對應。 發布最新版本的容器前，您可以先預覽 儲存容器
若要預覽容器，請在 Google
選擇容器版本來設定代碼管理工具網頁介面
，然後選取「Preview」。持續追蹤
因為後續步驟會用到這個預覽網址。
接下來，請將下列活動新增至應用程式的
AndroidManifest.xml 檔案：
<!-- Google Tag Manager Preview Activity -->
<activity
android:name="com.google.tagmanager.PreviewActivity"
android:label="@string/app_name"
android:noHistory="true" > <!-- Optional, removes the PreviewActivity from activity stack. -->
<intent-filter>
<data android:scheme="tagmanager.c.application_package_name" />
<action android:name="android.intent.action.VIEW" />
<category android:name="android.intent.category.DEFAULT" />
<category android:name="android.intent.category.BROWSABLE"/>
</intent-filter>
</activity>
在模擬器或實體裝置上開啟連結，即可執行以下操作： 在應用程式中預覽草稿容器
當您準備好將草稿設定值提供給 應用程式， 發布容器。
進階設定
行動版 Google 代碼管理工具有多項進階設定 這些選項可讓您根據執行階段條件選取值 手動重新整理容器，並取得開啟的其他選項 容器以下各節將概述一些最常見的 儲存空間設定
開啟容器的進階選項
Google 代碼管理工具 SDK 提供多種開啟方式 可讓您進一步掌控載入程序的容器：
TagManager.openContainer()
TagManager.openContainer() 是最高級別且最具彈性的 API，用於開啟
都會在 Docker 容器中執行此函式會立即傳回包含預設容器
如果未儲存任何檔案
則能以非同步方式從磁碟或網路載入容器
或儲存的容器還不是最新狀態 (超過 12 小時)。
mContainer = tagManager.openContainer(CONTAINER_ID, new Container.Callback() {
// Called when a refresh is about to begin for the given refresh type.
@Override
public void containerRefreshBegin(Container container, RefreshType refreshType) {
// Notify UI that the Container refresh is beginning.
}
// Called when a successful refresh occurred for the given refresh type.
@Override
public void containerRefreshSuccess(Container container, RefreshType refreshType]) {
// Notify UI that Container is ready.
}
// Called when a refresh failed for the given refresh type.
@Override
public void containerRefreshFailure(Container container,
RefreshType refreshType,
RefreshFailure refreshFailure) {
// Notify UI that the Container refresh has failed.
}
在載入過程中，有 TagManager.openContainer() 個問題
多個生命週期回呼，您的程式碼就可瞭解
是否開始載入要求、要求失敗或成功的原因，以及
容器則是從磁碟或網路載入
除非應用程式可接受使用預設值，否則 您需要使用這些回呼來知道儲存或網路 容器載入完畢。請注意，您將無法載入已儲存的或 如果這是第一次執行應用程式，而且沒有網路容器 網路連線。
TagManager.openContainer() 通過下列enum
做為這些回呼的引數：
RefreshType
| 值 | 說明 |
|---|---|
Container.Callback.SAVED
|
重新整理要求會載入儲存在本機的容器。 |
Container.Callback.NETWORK
|
重新整理要求會透過網路載入容器。 |
RefreshFailure
| 值 | 說明 |
|---|---|
Container.Callback.NO_SAVED_CONTAINER
|
沒有可用的已儲存容器。 |
Container.Callback.IO_ERROR
|
無法重新整理容器的 I/O 錯誤。 |
Container.Callback.NO_NETWORK
| 沒有可用的網路連線。 |
Container.Callback.NETWORK_ERROR
|
發生網路錯誤。 |
Container.Callback.SERVER_ERROR
|
伺服器發生錯誤， |
Container.Callback.UNKNOWN_ERROR
|
發生無法分類的錯誤。 |
開啟非預設與最新容器的方法
ContainerOpener 結束TagManager.openContainer()
並提供兩種開啟容器的簡便方法：
ContainerOpener.openContainer(..., Notifier notifier)和
ContainerOpener.openContainer(..., Long timeoutInMillis)。
這些方法都會接受列舉，要求使用非預設或 更新容器
建議大多數應用程式使用 OpenType.PREFER_NON_DEFAULT，
會在指定內
逾時期限，即使容器較大
超過 12 小時。如果傳回過時的已儲存容器，也會
非同步網路要求
使用 OpenType.PREFER_NON_DEFAULT 時，這是預設值
如果沒有其他可用容器，或逾時期限
。
OpenType.PREFER_FRESH 嘗試從以下時間傳回新容器：
在指定逾時期限內排除磁碟或網路
如果網路包含已儲存的容器
連線無法使用且/或超過逾時期限。
不建議使用 OpenType.PREFER_FRESH
對使用者體驗產生明顯影響
例如 UI 旗標或顯示字串您也可以使用
Container.refresh()
隨時
強制執行網路容器要求
這兩種方便的方法都是非阻塞。
ContainerOpener.openContainer(..., Long timeoutInMillis) 會傳回
ContainerOpener.ContainerFuture 物件，其 get 方法會傳回
Container 載入後立即執行 (但 仍會封鎖)。
ContainerOpener.openContainer(..., Notifier notifier) 方法會採用單一回呼
系統會在有可用容器時呼叫
可用來防止主執行緒封鎖主執行緒
這兩種方法的預設逾時期限為
2000 毫秒。
使用規則評估執行階段的巨集
容器可以在執行階段透過規則評估值。可根據規則進行設定 例如裝置語言、平台或任何其他巨集值適用對象 例如，您可以運用規則根據 以及裝置在執行階段的語言使用 GCP 控制台 規則：
接著，您就可以為每個語言建立值收集巨集，並將 規則，並插入適當的語言代碼。當這個容器 發布後，您的應用程式就會顯示本地化的螢幕 字串，視使用者裝置在執行階段的語言而定。
請注意，如果預設容器需要規則，您必須使用 二進位容器檔案做為預設選項 都會在 Docker 容器中執行
二進位檔預設容器檔案
需要規則的預設容器應使用二進位容器檔案 而非 JSON file 設為預設容器，二進位檔容器支援判定 巨集值在執行階段套用 Google 代碼管理工具規則時， JSON 檔案不會
您可以從 Google 代碼管理工具網站下載二進位容器檔案
介面和 API
應新增至專案的
/assets/tagmanager/ 資料夾，並採用以下格式：
/assets/tagmanager/GTM-XXXX，其中檔案名稱代表
容器 ID
如果是 JSON 檔案 以及二進位容器檔案，SDK 會使用二進位容器 檔案設為預設容器
使用函式呼叫巨集
函式呼叫巨集是設為 您在應用程式中指定的函式即可函式呼叫巨集可用於 結合執行階段值與您的 Google 代碼管理工具規則，例如 根據設定在執行階段中向使用者顯示何種價格 裝置的語言和貨幣。
如要設定函式呼叫巨集，請按照下列步驟操作：
- 在 Google 代碼管理工具網頁介面中定義函式呼叫巨集。 您可以選擇將引數設為鍵/值組合。
- 使用以下指令，在應用程式中註冊
FunctionCallMacroHandlerContainer.registerFunctionCallMacroHandler()和您設定的函式名稱 導入這個鍵，並覆寫其getValue()方法：/** * Registers a function call macro handler. * * @param functionName The function name field, as defined in the Google Tag * Manager web interface. */ mContainer.registerFunctionCallMacroHandler(functionName, new FunctionCallMacroHandler() { /** * This code will execute when any custom macro's rule(s) evaluate to true. * The code should check the functionName and process accordingly. * * @param functionName Corresponds to the function name field defined * in the Google Tag Manager web interface. * @param parameters An optional map of parameters * as defined in the Google Tag Manager web interface. */ @Override public Object getValue(String functionName, Map<String, Object> parameters)) { if (functionName.equals("myConfiguredFunctionName")) { // Process and return the calculated value of this macro accordingly. return macro_value } return null; } });
使用函式呼叫標記
函式呼叫代碼可讓預先註冊的函式在每次發生時執行
系統會將事件推送至資料層，而代碼規則
得出的值為 true。
如何設定函式呼叫代碼：
- 在 Google 代碼管理工具網頁介面中定義函式呼叫代碼。 您可以選擇將引數設為鍵/值組合。
- 使用下列程式碼，註冊應用程式中的函式呼叫標記處理常式：
Container.registerFunctionCallTagHandler()：/** * Register a function call tag handler. * * @param functionName The function name, which corresponds to the function name field * Google Tag Manager web interface. */ mContainer.registerFunctionCallTagHandler(functionName, new FunctionCallTagHandler() { /** * This method will be called when any custom tag's rule(s) evaluates to true. * The code should check the functionName and process accordingly. * * @param functionName The functionName passed to the functionCallTagHandler. * @param parameters An optional map of parameters as defined in the Google * Tag Manager web interface. */ @Override public void execute(String functionName, Map<String, Object> parameters) { if (functionName.equals("myConfiguredFunctionName")) { // Process accordingly. } } });
設定自訂重新整理週期
Google 代碼管理工具 SDK 會嘗試擷取
如果目前容器存在時間超過 12 小時，就會看見新的容器。如要設定
自訂容器重新整理期間，請使用
Timer
，如
範例：
timer.scheduleTask(new TimerTask() {
@Override
public void run() {
mContainer.refresh();
}
}, delay, <new_period_in milliseconds>);
使用 Logger 進行偵錯
根據預設，Google 代碼管理工具 SDK 會在記錄中列印錯誤和警告。
啟用更詳細的記錄對於偵錯會很有幫助，而且
實作自己的 Logger：
TagManager.setLogger，如以下範例所示：
TagManager tagManager = TagManager.getInstance(this);
tagManager.setLogger(new Logger() {
final String TAG = "myGtmLogger";
// Log output with verbosity level of DEBUG.
@Override
public void d(String arg0) {
Log.d(TAG, arg0);
}
// Log exceptions when provided.
@Override
public void d(String arg0, Throwable arg1) {
Log.d(TAG, arg0);
arg1.printStackTrace();
}
// Rest of the unimplemented Logger methods.
});
或者，您也可以使用以下方法設定現有 Logger 的 LogLevel：
TagManager.getLogger().setLogLevel(LogLevel)
,
如下所示：
// Change the LogLevel to INFO to enable logging at INFO and higher levels. TagManager tagManager = TagManager.getInstance(this); tagManager.getLogger().setLogLevel(LogLevel.INFO);