Android v4 - 使用入门

注意： 本指南介绍了旧版 Google 代码实现方式 Android 应用管理器。 新用户应当使用 跟踪代码管理器和 Firebase 来实现 Google 跟踪代码管理器 。

简介

借助 Google 跟踪代码管理器，开发者可以在其移动应用中更改配置值 直接使用 Google 跟踪代码管理器界面，而不必重新生成并重新提交应用二进制文件 应用市场

这对于管理应用中可能需要的任何配置值或标志非常有用 包括：

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

还可以在运行时使用规则评估配置值，从而实现动态 配置，例如：

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

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

准备工作

在开始学习本入门指南之前，请先完成以下步骤：

• 安装Android SDK
• 下载 Google Play 服务 SDK
• 创建 Google 跟踪代码管理器账号
• 配置 Google 跟踪代码管理器容器

完成上述步骤后，本指南的其余部分将逐步介绍如何 在您的 Android 应用中配置和使用 Google 跟踪代码管理器。

使用入门

按照本使用入门指南中的说明操作后，您将了解如何：

• 将 Google 跟踪代码管理器添加到您的项目中
• 在您的应用中初始化跟踪代码管理器
• 从跟踪代码管理器容器获取配置值
• 将值和事件推送到 dataLayer
• 预览、调试和发布您的容器

本指南使用的是 Cute Animals 示例应用程序 Google Play 服务 SDK。 此项目的完整源代码位于：<android-sdk-directory>/extras/google/google_play_services/tagmanager/cuteanimals。

1. 将 Google 跟踪代码管理器添加到您的项目中

要将 Google 跟踪代码管理器添加到您的项目中，请执行以下操作：

1. <ph type="x-smartling-placeholder"></ph> 设置 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 跟踪代码管理器网页界面中配置了容器， 完成后请返回此步骤。

Google 跟踪代码管理器会在您的应用首次运行时使用默认容器。默认 只要能够从存储分区中检索到新的容器， 。

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

1. 登录 Google 跟踪代码管理器网页界面。
2. 选择您要下载的容器的版本。
3. 点击下载按钮，获取容器二进制文件。
4. 将下载的容器二进制文件作为原始资源添加到项目中。
   1. 如果 raw 子文件夹下的 “<project-root>/res/”不存在，请创建。
   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() 的调用是非阻塞的 并返回 <ph type="x-smartling-placeholder"></ph> 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);

   注意：默认情况下，容器符合刷新条件 每 12 小时通过网络传输一次。了解如何手动刷新容器。

   创建 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 跟踪代码管理器的值集合变量。例如，以下方法 检索我们决定用于界面元素的最新颜色，并将其作为 整数：

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

此代码会执行两项操作，以从容器中检索颜色名称：

1. 使用以下方法从 ContainerHolder 获取 Container： <ph type="x-smartling-placeholder"></ph> ContainerHolder.getContainer()。
2. 使用 <ph type="x-smartling-placeholder"></ph> 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 获取值，请使用 <ph type="x-smartling-placeholder"></ph> DataLayer.get(key)。

将事件推送到 dataLayer

将事件推送到 dataLayer 可让您将应用代码与 来响应这些事件而触发的代码。

例如，您不必将 Google Analytics 屏幕浏览跟踪调用硬编码到您的应用中， 则可以将屏幕事件推送到 dataLayer，并通过 Google 跟踪代码管理器网页界面。这样，您就可以灵活修改该代码 无需更新应用代码即可响应屏幕事件的其他代码。

如需将事件推送到 dataLayer，请遵循以下模式：

1. 获取 DataLayer 单例：

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

2. 使用 推送事件 DataLayer.pushEvent():

   dataLayer.pushEvent("openScreen", DataLayer.mapOf("screenName", screenName));

   <ph type="x-smartling-placeholder"></ph> 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 跟踪代码管理器，您可以预览容器的各个版本 方法是在网页界面中生成链接和二维码，然后使用它们打开您的应用。 您还可以启用详细日志记录模式，以调试任何意外行为。

正在预览

要预览容器的某个版本，请按以下步骤操作：

1. 将以下预览 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" />

2. 在 Google 跟踪代码管理器网页界面中生成预览链接 <ph type="x-smartling-placeholder">
   </ph>
   1. 登录 Google 跟踪代码管理器
   2. 选择容器版本以进行预览
   3. 点击预览按钮
   4. 输入您应用的软件包名称，然后点击生成“开始预览”链接
3. 使用生成的链接或二维码启动您的应用
4. 您可以点击生成“结束预览”链接生成的链接来退出预览模式 选项。

调试

如果您需要对容器实现进行问题排查，请调用 <ph type="x-smartling-placeholder"></ph> 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 分钟只能调用一次，否则将为空操作。

注意：该代码段使用 ContainerHolderSingleton 实用程序类（参见初始化示例） 。

来自样本应用的参考代码段

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