TagManager

public class TagManager extends Object

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 Container.getBoolean(String), Container.getDouble(String), Container.getLong(String), Container.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 ContainerHolder.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.

Public Method Summary

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 PendingResult.await(long, java.util.concurrent.TimeUnit), or PendingResult.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 PendingResult.await(long, java.util.concurrent.TimeUnit), or PendingResult.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 PendingResult.await(long, java.util.concurrent.TimeUnit), or PendingResult.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 PendingResult.await(long, java.util.concurrent.TimeUnit), or PendingResult.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.

Inherited Method Summary

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, ContainerHolder.getContainer() will return null and Result.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 PendingResult.setResultCallback(ResultCallback ) or ContainerHolder.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, ContainerHolder.getContainer() will return null and Result.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 PendingResult.setResultCallback(ResultCallback ) or ContainerHolder.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 PendingResult.await(long, java.util.concurrent.TimeUnit), or PendingResult.setResultCallback(com.google.android.gms.common.api.ResultCallback, long, java.util.concurrent.TimeUnit).

If a timeout occurs, the container available from ContainerHolder.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, Result.getStatus() will return an error.

Use Container.isDefault() if you need to know whether the container you have is a default container. Use Container.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 PendingResult.setResultCallback(ResultCallback ) or ContainerHolder.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 PendingResult.await(long, java.util.concurrent.TimeUnit), or PendingResult.setResultCallback(com.google.android.gms.common.api.ResultCallback, long, java.util.concurrent.TimeUnit).

If a timeout occurs, the container available from ContainerHolder.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, Result.getStatus() will return an error.

Use Container.isDefault() if you need to know whether the container you have is a default container. Use Container.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 PendingResult.setResultCallback(ResultCallback ) or ContainerHolder.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 PendingResult.await(long, java.util.concurrent.TimeUnit), or PendingResult.setResultCallback(com.google.android.gms.common.api.ResultCallback, long, java.util.concurrent.TimeUnit).

If a timeout occurs, the container available from ContainerHolder.getContainer() will (initially) be a default container, if available (if no default container is available, ContainerHolder.getContainer() will return null and Result.getStatus() will return an error). Use Container.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 PendingResult.setResultCallback(ResultCallback ) or ContainerHolder.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 PendingResult.await(long, java.util.concurrent.TimeUnit), or PendingResult.setResultCallback(com.google.android.gms.common.api.ResultCallback, long, java.util.concurrent.TimeUnit).

If a timeout occurs, the container available from ContainerHolder.getContainer() will (initially) be a default container, if available (if no default container is available, ContainerHolder.getContainer() will return null and Result.getStatus() will return an error). Use Container.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 PendingResult.setResultCallback(ResultCallback ) or ContainerHolder.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.