public class

TagManager

extends Object
java.lang.Object
   ↳ com.google.android.gms.tagmanager.TagManager

Class Overview

This is the mobile implementation of Google Tag Manager (GTM). Sample usage: 

 TagManager tagManager = TagManager.getInstance(context);
 PendingResult pending = tagManager.loadContainerPreferNonDefault(
         myContainerId,    // container ID of the form "GTM-XXXX"
         R.raw.GTM-XXXX,   // the resource ID of the default container
         true);            // the default container is in JSON format (as opposed to binary)
 ...
 ContainerHolder containerHolder = pending.await(2, TimeUnit.SECONDS);
 if (containerHolder.getStatus() != Status.RESULT_SUCCESS) {
        // deal with failure
 }
 String value = containerHolder.getContainer().getString("myKey");

 DataLayer dataLayer = TagManager.getInstance(context).getDataLayer();
 dataLayer.pushEvent("openScreen", DataLayer.mapOf("screenName", "Main Page"));
A container is a collection of macros, tags and rules. It is created within the GTM application, and is assigned a container ID. This container ID is the one used within this API.

The Container class provides methods for retrieving values given a key. The routines getBoolean(String), getDouble(String), getLong(String), getString(String) return the current value for the key of a value collection macro, depending on the rules associated with the container.

As an example, if your container has a value collection macro with a key speed whose value is 32, and the enabling rule is Language is "en"; and another value collection macro with a key speed whose value is 45, and the enabling rule is Language is not "en", then making the following call: 

 container.getLong("speed")
will return either 32 if the current language of the device is English, or 45 otherwise.

The data layer is a map holding generic information about the application. The DataLayer class provides methods to push and retrieve data from the data layer. Pushing an event key to the data layer will cause tags that match this event to fire.

An initial version of the container is bundled with the application. It should be placed as a raw resource in the res/raw directory. When you call one of the loadContainer... methods, you'll pass in the assigned ID (R.raw.filename); the container will be returned with those bundled rules/macros. You will create the container in the UI and use the Download button to download it. Alternatively, you can provide a JSON file containing key/value pairs.

You can modify the container in the UI and publish a new version. In that case, the next time the mobile app refreshes the container from the network (currently every 12 hours), it will get that new version. When you call getContainer(), it'll make that new container active and return it. Calling one of the get... routines on that container will return a value computed using the most recent rules.

The downloaded container is saved locally; when you call one of the loadContainer... methods, it will first load the default container, and will then load any saved container. If none is found, or if it is older than 12 hours, it will try to retrieve a newer version from the network.

Summary

Public Methods
DataLayer getDataLayer()
Returns the data layer object that is used by the tag manager.
static TagManager getInstance(Context context)
Get the singleton instance of the TagManager class, creating it if necessary.
PendingResult<ContainerHolder> loadContainerDefaultOnly(String containerId, int defaultContainerResourceId, Handler handler)

The ContainerHolder will be available from the returned PendingResult as soon as either of the following happens:

  • the default container is loaded, or
  • no default container is found.
PendingResult<ContainerHolder> loadContainerDefaultOnly(String containerId, int defaultContainerResourceId)

The ContainerHolder will be available from the returned PendingResult as soon as either of the following happens:

  • the default container is loaded, or
  • no default container is found.
PendingResult<ContainerHolder> loadContainerPreferFresh(String containerId, int defaultContainerResourceId)

The ContainerHolder will be available from the returned PendingResult as soon as one of the following happens:

PendingResult<ContainerHolder> loadContainerPreferFresh(String containerId, int defaultContainerResourceId, Handler handler)

The ContainerHolder will be available from the returned PendingResult as soon as one of the following happens:

PendingResult<ContainerHolder> loadContainerPreferNonDefault(String containerId, int defaultContainerResourceId)

The ContainerHolder will be available from the returned PendingResult as soon as one of the following happens:

PendingResult<ContainerHolder> loadContainerPreferNonDefault(String containerId, int defaultContainerResourceId, Handler handler)

The ContainerHolder will be available from the returned PendingResult as soon as one of the following happens:

void setVerboseLoggingEnabled(boolean enableVerboseLogging)
Sets whether or not verbose logging is enabled.
[Expand]
Inherited Methods
From class java.lang.Object

Public Methods

public DataLayer getDataLayer ()

Returns the data layer object that is used by the tag manager.

public static TagManager getInstance (Context context)

Get the singleton instance of the TagManager class, creating it if necessary.

public PendingResult<ContainerHolder> loadContainerDefaultOnly (String containerId, int defaultContainerResourceId, Handler handler)

The ContainerHolder will be available from the returned PendingResult as soon as either of the following happens:

  • the default container is loaded, or
  • no default container is found.

If no default container is found, getContainer() will return null and getStatus() will return an error).

The returned ContainerHolder will not be updated from disk, or from the network. The intended use is during development: this provides a way for developers to add new container key/value pairs without having to use the GTM UI or needing a network connection. A developer can add new key/value pairs to a JSON default container, and then use this call to load that container.

You should not call any of the loadContainer methods a second time with a given containerId, since a different ContainerHolder will be returned which will hold a different container. Those separate containers will each fire any tags within them, which would cause double-tagging.

Parameters
containerId the ID of the container to load
defaultContainerResourceId the resource ID of the default container (for example, R.raw.GTM_XYZZY if you stored your container in res/raw/GTM_XYZZY).
handler the handler on whose thread the callback set with setResultCallback(ResultCallback) or setContainerAvailableListener(ContainerHolder.ContainerAvailableListener) is invoked

public PendingResult<ContainerHolder> loadContainerDefaultOnly (String containerId, int defaultContainerResourceId)

The ContainerHolder will be available from the returned PendingResult as soon as either of the following happens:

  • the default container is loaded, or
  • no default container is found.

If no default container is found, getContainer() will return null and getStatus() will return an error).

The returned ContainerHolder will not be updated from disk, or from the network. The intended use is during development: this provides a way for developers to add new container key/value pairs without having to use the GTM UI or needing a network connection. A developer can add new key/value pairs to a JSON default container, and then use this call to load that container.

You should not call any of the loadContainer methods a second time with a given containerId, since a different ContainerHolder will be returned which will hold a different container. Those separate containers will each fire any tags within them, which would cause double-tagging.

Any callback set by setResultCallback(ResultCallback) or setContainerAvailableListener(ContainerHolder.ContainerAvailableListener), will be invoked on the main looper thread.

Parameters
containerId the ID of the container to load
defaultContainerResourceId the resource ID of the default container (for example, R.raw.GTM_XYZZY if you stored your container in res/raw/GTM_XYZZY).

public PendingResult<ContainerHolder> loadContainerPreferFresh (String containerId, int defaultContainerResourceId)

The ContainerHolder will be available from the returned PendingResult as soon as one of the following happens:

If a timeout occurs, the container available from getContainer() will be:

  • a saved container which has not recently been refreshed (stale).
  • a default container (if no stale container is available, or could not be loaded before the timeout).
  • null (if no default container is available, or a saved or default container couldn't be loaded before the timeout). In this case, getStatus() will return an error.
Use isDefault() if you need to know whether the container you have is a default container. Use getLastRefreshTime() to determine when the container was last refreshed.

You should not call any of the loadContainer methods a second time with a given containerId, since a different ContainerHolder will be returned which will hold a different container. Those separate containers will each fire any tags within them, which would cause double-tagging.

Any callback set by setResultCallback(ResultCallback) or setContainerAvailableListener(ContainerHolder.ContainerAvailableListener), will be invoked on the main looper thread.

Parameters
containerId the ID of the container to load
defaultContainerResourceId the resource ID of the default container (for example, R.raw.GTM_XYZZY if you stored your container in res/raw/GTM_XYZZY). Pass -1 if you have no default container.

public PendingResult<ContainerHolder> loadContainerPreferFresh (String containerId, int defaultContainerResourceId, Handler handler)

The ContainerHolder will be available from the returned PendingResult as soon as one of the following happens:

If a timeout occurs, the container available from getContainer() will be:

  • a saved container which has not recently been refreshed (stale).
  • a default container (if no stale container is available, or could not be loaded before the timeout).
  • null (if no default container is available, or a saved or default container couldn't be loaded before the timeout). In this case, getStatus() will return an error.
Use isDefault() if you need to know whether the container you have is a default container. Use getLastRefreshTime() to determine when the container was last refreshed.

You should not call any of the loadContainer methods a second time with a given containerId, since a different ContainerHolder will be returned which will hold a different container. Those separate containers will each fire any tags within them, which would cause double-tagging.

Parameters
containerId the ID of the container to load
defaultContainerResourceId the resource ID of the default container (for example, R.raw.GTM_XYZZY if you stored your container in res/raw/GTM_XYZZY). Pass -1 if you have no default container.
handler the handler on whose thread the callback set with setResultCallback(ResultCallback) or setContainerAvailableListener(ContainerHolder.ContainerAvailableListener) is invoked

public PendingResult<ContainerHolder> loadContainerPreferNonDefault (String containerId, int defaultContainerResourceId)

The ContainerHolder will be available from the returned PendingResult as soon as one of the following happens:

If a timeout occurs, the container available from getContainer() will (initially) be a default container, if available (if no default container is available, getContainer() will return null and getStatus() will return an error). Use isDefault() if you need to know whether the container you have is a default container.

You should not call any of the loadContainer methods a second time with a given containerId, since a different ContainerHolder will be returned which will hold a different container. Those separate containers will each fire any tags within them, which would cause double-tagging.

Any callback set by setResultCallback(ResultCallback) or setContainerAvailableListener(ContainerHolder.ContainerAvailableListener), will be invoked on the main looper thread.

Parameters
containerId the ID of the container to load
defaultContainerResourceId the resource ID of the default container (for example, R.raw.GTM_XYZZY if you stored your container in res/raw/GTM_XYZZY). Pass -1 if you have no default container.

public PendingResult<ContainerHolder> loadContainerPreferNonDefault (String containerId, int defaultContainerResourceId, Handler handler)

The ContainerHolder will be available from the returned PendingResult as soon as one of the following happens:

If a timeout occurs, the container available from getContainer() will (initially) be a default container, if available (if no default container is available, getContainer() will return null and getStatus() will return an error). Use isDefault() if you need to know whether the container you have is a default container.

You should not call any of the loadContainer methods a second time with a given containerId, since a different ContainerHolder will be returned which will hold a different container. Those separate containers will each fire any tags within them, which would cause double-tagging.

Parameters
containerId the ID of the container to load
defaultContainerResourceId the resource ID of the default container (for example, R.raw.GTM_XYZZY if you stored your container in res/raw/GTM_XYZZY). Pass -1 if you have no default container.
handler the handler on whose thread the callback set with setResultCallback(ResultCallback) or setContainerAvailableListener(ContainerHolder.ContainerAvailableListener) is invoked

public void setVerboseLoggingEnabled (boolean enableVerboseLogging)

Sets whether or not verbose logging is enabled. By default, verbose logging is not enabled.