Android v3（旧版）- 概览

。

本开发者指南介绍了如何在 。

简介

借助 Google 跟踪代码管理器，开发者可以更改配置 通过 Google 跟踪代码管理器在移动应用中植入 而无需重新生成应用二进制文件并将其重新提交给应用 市场。

这对于管理任何配置值非常有用 或标志（将来可能需要更改的标志）， 包括：

• 各种界面设置和显示字符串
• 应用中投放的广告的尺寸、位置或类型
• 游戏设置

也可以在运行时使用规则评估配置值 启用动态配置，例如：

• 根据屏幕尺寸确定横幅广告尺寸
• 使用语言和位置配置界面元素

Google 跟踪代码管理器还支持动态实现跟踪代码 和像素。开发者可以将重要事件推送到数据中， 层，并决定应触发哪些跟踪代码或像素。 跟踪代码管理器目前支持以下代码：

• Google移动应用分析
• 自定义函数调用代码

准备工作

在使用本入门指南之前，您需要做好以下准备：

• 一个 Google 跟踪代码管理器账号
• 新的跟踪代码管理器 容器和值收集宏
• Android 版移动应用，其中实现 Google 跟踪代码管理器
• Google Analytics 服务 SDK，其中包含跟踪代码管理器库。

如果您刚开始接触 Google 跟踪代码管理器，我们建议您 请先详细了解容器、宏和规则（帮助中心），然后再继续本指南。

使用入门

本部分将指导开发者完成典型的跟踪代码管理器工作流程：

1. 将 Google 跟踪代码管理器 SDK 添加到您的项目中
2. 设置默认容器值
3. 打开容器
4. 从容器中获取配置值
5. 将事件推送到 DataLayer
6. 预览和发布容器

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 跟踪代码管理器会在您的应用首次运行时使用默认容器。默认 系统将使用容器，直到应用能够通过容器检索到 。

如需下载默认容器二进制文件并将其添加到您的应用，请按以下步骤操作：

1. 登录 Google 跟踪代码管理器网页界面。
2. 选择您要下载的容器的版本。
3. 点击下载按钮，获取容器二进制文件。
4. 将二进制文件添加到 以下路径：<project-root>/assets/tagmanager/

默认文件名应为容器 ID（例如 GTM-1234）。安装 下载了二进制文件，请务必从文件名中移除版本后缀 以确保遵循正确的命名惯例。

虽然我们建议使用二进制文件，但如果您的容器不包含规则或代码， 则可以选择使用简单的 JSON 文件。 文件必须位于新的 /assets/tagmanager 中 文件夹中，并且应遵循以下命名惯例： <Container_ID>.json。例如，如果您的容器 ID 为 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) 用于 从本地存储空间请求已保存的容器通过处理 mContainer 在 containerAvailable 回调中，我们会确保 主线程未阻塞如果保存的容器存在时间已超过 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 是一个地图，可启用有关应用的运行时信息，例如触摸 事件或屏幕浏览事件，以提供给跟踪代码管理器宏和代码， 容器。

例如，将有关屏幕浏览的信息推送到 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。请稍候 此预览网址，因为您在后续步骤中会用到它。

接下来，将以下 Activity 添加到应用的 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，用于 容器。它会立即返回一个默认容器， 还会异步从磁盘或网络加载容器， 容器是否存在，或者保存的容器不是最新的（超过 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 在请求时间较长可能会明显影响用户体验的情况下， 例如使用界面标记或显示字符串您还可以使用 Container.refresh() 随时 来强制执行网络容器请求

这两种便捷方法都是非阻塞的。 ContainerOpener.openContainer(..., Long timeoutInMillis) 会返回 ContainerOpener.ContainerFuture 对象，其 get 方法会返回 Container（但在此之前，该操作将阻塞）。 ContainerOpener.openContainer(..., Notifier notifier) 方法接受单个回调， 在容器可用时调用， 可用于防止阻塞主线程。 两种方法的默认超时期限均为 2000 毫秒。

使用规则在运行时评估宏

容器可以在运行时使用规则评估值。规则可能 例如设备语言、平台或任何其他宏值对于 例如，可以使用规则根据 设备的语言。您可以使用 以下规则：

然后，您可以为每种语言创建值集合宏，并将此 规则，插入相应的语言代码。这个容器 发布后，您的应用将能够在 字符串，具体取决于用户设备在运行时的语言。

请注意，如果您的默认容器需要规则，您必须使用 二进制文件容器文件 容器。

详细了解如何配置规则（帮助中心）。

默认二进制文件容器文件

需要规则的默认容器应使用二进制容器文件 而不是 JSON 文件作为默认容器。二元容器支持确定 宏值，而 JSON 文件不能。

二进制容器文件可从 Google 跟踪代码管理器网站下载 和 应该添加到项目的 /assets/tagmanager/ 文件夹，并采用以下格式： /assets/tagmanager/GTM-XXXX，其中文件名表示您的 容器 ID

在有 JSON 文件的情况下 以及二进制容器文件存在时，SDK 将使用二进制容器 文件作为默认容器。

使用函数调用宏

函数调用宏是设置为 指定函数函数调用宏可用于 将运行时值纳入您的 Google 跟踪代码管理器规则中，例如 在运行时根据配置的 设备的语言和货币

如需配置函数调用宏，请执行以下操作：

1. 在 Google 跟踪代码管理器网页界面中定义函数调用宏。 您可以选择将参数配置为键值对。
2. 使用以下代码在应用中注册 FunctionCallMacroHandler： Container.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。

如需配置函数调用代码，请执行以下操作：

1. 在 Google 跟踪代码管理器网页界面中定义函数调用代码。 您可以选择将参数配置为键值对。
2. 使用以下代码在应用中注册函数调用标记处理程序： 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.

});

或者，你可以使用 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);