Summary: Methods | Inherited Methods | [Expand All]
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.<I>filename</I>`); 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
void | dispatch() Manually dispatches queued events (tracking pixels, etc) if a network connection is available.
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) 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, 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> | loadContainerPreferFresh(String containerId, int defaultContainerResourceId) The `ContainerHolder` will be available from the returned `PendingResult` as soon as one of the following happens: a saved container which has been recently refreshed is loaded, a network container is loaded or a network error occurs, or a timeout occurs (as specified in `await(long, java.util.concurrent.TimeUnit)`, or `setResultCallback(com.google.android.gms.common.api.ResultCallback, long, java.util.concurrent.TimeUnit)`.
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: a saved container which has been recently refreshed is loaded, a network container is loaded or a network error occurs, or a timeout occurs (as specified in `await(long, java.util.concurrent.TimeUnit)`, or `setResultCallback(com.google.android.gms.common.api.ResultCallback, long, java.util.concurrent.TimeUnit)`.
PendingResult<ContainerHolder> | loadContainerPreferNonDefault(String containerId, int defaultContainerResourceId) The `ContainerHolder` will be available from the returned `PendingResult` as soon as one of the following happens: a saved container is loaded, or if there is no saved container, a network container is loaded or a network error occurs, or a timeout occurs (as specified in `await(long, java.util.concurrent.TimeUnit)`, or `setResultCallback(com.google.android.gms.common.api.ResultCallback, long, java.util.concurrent.TimeUnit)`.
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: a saved container is loaded, if there is no saved container, a network container is loaded or a network error occurs, or a timeout occurs (as specified in `await(long, java.util.concurrent.TimeUnit)`, or `setResultCallback(com.google.android.gms.common.api.ResultCallback, long, java.util.concurrent.TimeUnit)`.
void | setVerboseLoggingEnabled(boolean enableVerboseLogging) Sets whether or not verbose logging is enabled.

[Expand] Inherited Methods
From class java.lang.Object
Object | clone()
boolean | equals(Object arg0)
void | finalize()
final Class<?> | getClass()
int | hashCode()
final void | notify()
final void | notifyAll()
String | toString()
final void | wait(long arg0, int arg1)
final void | wait(long arg0)
final void | wait()

## Public Methods

#### public void dispatch ()

Manually dispatches queued events (tracking pixels, etc) if a network connection is available. Dispatching after significant application events can help to ensure accurate reporting. Calling dispatch frequently can cause excessive battery drain and should be avoided.

#### 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)

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> 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> loadContainerPreferFresh (String containerId, int defaultContainerResourceId)

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

- a saved container which has been recently refreshed is loaded,
- a network container is loaded or a network error occurs, or
- a timeout occurs (as specified in `await(long, java.util.concurrent.TimeUnit)`, or `setResultCallback(com.google.android.gms.common.api.ResultCallback, long, java.util.concurrent.TimeUnit)`.

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:

- a saved container which has been recently refreshed is loaded,
- a network container is loaded or a network error occurs, or
- a timeout occurs (as specified in `await(long, java.util.concurrent.TimeUnit)`, or `setResultCallback(com.google.android.gms.common.api.ResultCallback, long, java.util.concurrent.TimeUnit)`.

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:

- a saved container is loaded, or
- if there is no saved container, a network container is loaded or a network error occurs, or
- a timeout occurs (as specified in `await(long, java.util.concurrent.TimeUnit)`, or `setResultCallback(com.google.android.gms.common.api.ResultCallback, long, java.util.concurrent.TimeUnit)`.

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:

- a saved container is loaded,
- if there is no saved container, a network container is loaded or a network error occurs, or
- a timeout occurs (as specified in `await(long, java.util.concurrent.TimeUnit)`, or `setResultCallback(com.google.android.gms.common.api.ResultCallback, long, java.util.concurrent.TimeUnit)`.

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.