Android v4 - 使用入门

简介

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

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

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

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

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

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. 如果您使用的是 Android Studio 以外的 IDE，请将以下权限添加到 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 单例

    每次运行应用时，您只能保留一个 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 跟踪代码管理器的值收集变量定义。例如，以下方法可检索我们决定对界面元素使用的最新颜色，并将其作为整数返回：

/**
 * 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，您可以将应用代码与您可能为了响应这些事件而触发的代码分开。

例如，您无需将 Google Analytics（分析）屏幕浏览跟踪调用硬编码到您的应用中，而是可以通过将屏幕事件推送到 dataLayer，并通过 Google 跟踪代码管理器网页界面定义您的跟踪代码。这样一来，您就可以灵活修改该代码，或添加会响应屏幕事件的其他代码，而无需更新应用代码。

如需将事件推送到 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 码，然后使用它们打开您的应用，从而预览您的容器版本。您还可以启用详细日志记录模式来调试任何意外行为。

正在预览

如需预览容器的版本，请按以下步骤操作：

  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 跟踪代码管理器网页界面中生成预览链接
    1. 登录 Google 跟踪代码管理器
    2. 选择要预览的容器版本
    3. 点击预览按钮
    4. 输入应用的软件包名称，然后点击 Generate begin preview link
  3. 使用生成的链接或二维码启动您的应用
  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 分钟只能调用一次，否则它会是一个空操作。