简介
借助 Google 跟踪代码管理器,开发者可以使用 Google 跟踪代码管理器界面更改移动应用中的配置值,而无需重新生成应用二进制文件并将其重新提交到应用市场。
这对于管理应用中将来可能需要更改的任何配置值或标志非常有用,包括:
- 各种界面设置和显示字符串
- 您应用中投放的广告的尺寸、位置或类型
- 各种游戏设置
配置值还可在运行时使用规则进行评估,以实现以下动态配置:
- 根据屏幕尺寸确定广告横幅的尺寸
- 使用语言和位置配置界面元素
Google 跟踪代码管理器还支持在应用中动态实现跟踪代码和像素。开发者可以将重要事件推送到数据层,稍后再决定应触发哪些跟踪代码或像素。
准备工作
在开始阅读本入门指南之前,请完成以下步骤:
完成上述步骤后,本指南的其余部分将向您介绍如何在 Android 应用中配置和使用 Google 跟踪代码管理器。
使用入门
按照本入门指南中的说明,您将了解如何:
本指南使用的是来自 Google Play 服务 SDK 随附的 Cute Animals
示例应用的代码段。
此项目的完整源代码可在 <android-sdk-directory>/extras/google/google_play_services/tagmanager/cuteanimals
中找到。
1. 将 Google 跟踪代码管理器添加到您的项目中
若要将 Google 跟踪代码管理器添加到您的项目中,请执行以下操作:
- 设置 Google Play 服务 SDK。
- 如果您使用的是
Android Studio 以外的 IDE,请将以下权限添加到
AndroidManifest.xml
文件中:<!-- For TagManager SDK --> <uses-permission android:name="android.permission.INTERNET" /> <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
- 如需让
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 跟踪代码管理器网页界面。
- 选择您要下载的容器的版本。
- 点击下载按钮以检索容器二进制文件。
- 将下载的容器二进制文件作为原始资源添加到您的项目中。
- 如果
<project-root>/res/
下不存在raw
子文件夹,请创建该子文件夹。 - 如有必要,重命名容器二进制文件。它仅由小写字母、数字和下划线组成。
- 将容器二进制文件复制到文件夹
<project-root>/res/raw
。
- 如果
虽然我们建议使用二进制文件,但如果您的容器不包含规则或标记,您可以选择使用简单的 JSON 文件。
3. 初始化 Google 跟踪代码管理器
若要在您的应用中初始化 Google 跟踪代码管理器,请执行以下操作:
- 获取
TagManager
单例:TagManager tagManager = TagManager.getInstance(this);
- 使用
TagManager
单例发出加载容器的请求,并指定 Google 跟踪代码管理器容器 ID 以及您的默认容器文件。容器 ID 应为大写,且与 Google 跟踪代码管理器网页界面中的容器 ID 完全一致。对loadContainerPreferNonDefault()
的调用是非阻塞的,并且会返回PendingResult
:PendingResult<ContainerHolder> pending = tagManager.loadContainerPreferNonDefault(CONTAINER_ID, R.raw.defaultcontainer_binary);
- 使用
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)); }
此代码会执行两项操作,以便从容器中检索颜色名称:
- 使用
ContainerHolder.getContainer()
从ContainerHolder
获取Container
。 - 使用
Container.getString(key)
获取颜色值,您已在 Google 跟踪代码管理器网页界面中定义键和值。
5. 将事件和值推送到 dataLayer
Google 跟踪代码管理器还提供了一个 dataLayer
,您可以通过它推送应用的相关信息,这些信息可在应用的其他部分读取,或用于触发您在 Google 跟踪代码管理器网页界面中配置的代码。
将值推送到 dataLayer
dataLayer
提供了一层持久性层,用于存储可能要在应用的其他部分使用或用作 Google 跟踪代码管理器代码的输入的键值对。
如需将值推送到 dataLayer
,请遵循以下模式:
- 获取
DataLayer
单例:DataLayer dataLayer = TagManager.getInstance(context).getDataLayer();
- 使用
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
,请遵循以下模式:
- 获取
DataLayer
单例:DataLayer dataLayer = TagManager.getInstance(context).getDataLayer();
- 使用
DataLayer.pushEvent()
推送事件:dataLayer.pushEvent("openScreen", DataLayer.mapOf("screenName", screenName));
DataLayer.mapOf()
是一种实用程序方法,可用于轻松生成键值对的映射,用于在推送事件的同时更新dataLayer
。
6. 预览、调试和发布
在发布容器版本之前,您需要进行预览,以确保它可以按预期运行。通过 Google 跟踪代码管理器,您可以在网页界面中生成链接和二维码,然后使用它们打开您的应用,从而预览容器的各个版本。您还可以启用详细日志记录模式来调试任何意外行为。
正在预览
要预览容器的某个版本,请按以下步骤操作:
- 将此预览
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" />
- 在 Google 跟踪代码管理器网页界面中生成预览链接
- 登录 Google 跟踪代码管理器
- 选择要预览的容器版本
- 点击预览按钮
- 输入应用的软件包名称,然后点击生成“开始预览”链接
- 使用生成的链接或二维码启动您的应用
- 您可以点击网页界面中的生成“结束预览”链接选项生成的链接,从而退出预览模式。
调试
如果您需要对容器实现进行问题排查,请调用
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()
,否则将为空操作。