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. 使用 ResultCallbackContainerHolder 加载完成或超时后返回它:
    // 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,您可以将应用代码与可能希望为响应这些事件而触发的代码分开。

例如,您可以将屏幕事件推送到 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 跟踪代码管理器,您可以在网页界面中生成链接和二维码,然后使用它们打开您的应用,从而预览容器的各个版本。您还可以启用详细日志记录模式来调试任何意外行为。

正在预览

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

  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. 输入应用的软件包名称,然后点击生成“开始预览”链接
  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();

这是不会立即返回的异步调用。为了减少网络流量,每 15 分钟只能调用一次 refresh(),否则将为空操作。