Android v4 - Getting Started

Introduction

Google Tag Manager enables developers to change configuration values in their mobile application using the Google Tag Manager interface without having to rebuild and resubmit application binaries to app marketplaces.

This is useful for managing any configuration values or flags in your application that you may need to change in the future, including:

Various UI settings and display strings
Sizes, locations, or types of ads served in your application
Various Game settings

Configuration values may also be evaluated at runtime using rules, enabling dynamic configurations such as:

Using screen size to determine ad banner size
Using language and location to configure UI elements

Google TagManager also enables the dynamic implementation of tracking tags and pixels in applications. Developers can push important events into a data layer and decide later which tracking tags or pixels should be fired.

Before you Begin

Complete the following steps before you begin this getting started guide:

Install the Android SDK
Download the Google Play Services SDK
Create a Google Tag Manager account
Configure a Google Tag Manager container

Once you've completed these steps, the remainder of this guide will walk you through how to configure and use Google Tag Manager within your Android application.

Getting Started

After following this Getting Started guide, you'll understand how to:

Add Google Tag Manager to your project
Initialize Tag Manager in your application
Get configuration values from a Tag Manager container
Push values and events into the dataLayer
Preview, debug, and publish your container

This guide uses code snippets from the Cute Animals sample application included with the Google Play Services SDK . The complete source for this project is available in: < android-sdk-directory >/extras/google/google_play_services/tagmanager/cuteanimals .

1. Adding Google Tag Manager to your Project

To add Google Tag Manager to your project:

Set Up the Google Play Services SDK .

If you use an IDE other than Android Studio , add the following permissions to the AndroidManifest.xml file:

<!-- For TagManager SDK -->
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

To enable InstallReferrerReceiver to call the Google Analytics receiver to set the campaign data, add the following to the AndroidManifest.xml file:

< !-- 
  
 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. Adding a Default Container File to your Project

Google Tag Manager uses a default container on the first run of your application. The default container will cease to be used as soon as the app is able to retrieve a fresh container over the network.

To download and add a default container binary to your application:

Sign in to the Google Tag Manager web interface.
Select the Versionof the container you'd like to download.
Click the Downloadbutton to retrieve the container binary.
Add the downloaded container binary file to your project as a raw resource.
1. If the raw subfolder under <project-root>/res/ does not exist, create it.
2. Rename the container binary file if necessary. It consists of only lowercase letters, digits, and underscores.
3. Copy the container binary file to the folder <project-root>/res/raw .

Although using the binary file is recommended, if your container does not contain rules or tags, you may choose to use a simple JSON file instead.

3. Initializing Google Tag Manager

To initialize Google Tag Manager in your application:

Get the TagManager singleton:

TagManager tagManager = TagManager.getInstance(this);

Use the TagManager singleton to make a request to load a container, specifying a Google Tag Manager container ID as well as your default container file. The container ID should be uppercase and exactly match the container ID in the Google Tag Manager web interface. The call to loadContainerPreferNonDefault() is non-blocking and returns a PendingResult :
```
 PendingResult<ContainerHolder> 
  
 pending 
  
 = 
  
 tagManager 
 . 
 loadContainerPreferNonDefault 
 ( 
 CONTAINER_ID 
 , 
  
 R 
 . 
 raw 
 . 
 defaultcontainer_binary 
 ); 
```

Use a ResultCallback to return the ContainerHolder once it has finished loading or timed out:

 // 
  
 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 
 );

Creating a ContainerHolder Singleton

You should only maintain one instance of ContainerHolder per run of your application. That is why the above example uses a ContainerHolderSingleton utility class to manage access to the ContainerHolder instance. Here is what that ContainerHolderSingleton class looks like:

 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 
 ; 
 } 
 }

See a Code Snippet from the Sample Application

The following snippet shows the full pattern implemented in the onCreate() method of a sample Activity :

 package 
 com 
 . 
 google 
 . 
 android 
 . 
 tagmanager 
 . 
 examples 
 . 
 cuteanimals 
 ; 
 import 
  
 java.util.concurrent.TimeUnit 
 ; 
 import 
  
 java.util.Map 
 ; 
 import 
  
 android.app.Activity 
 ; 
 import 
  
 android.app.AlertDialog 
 ; 
 import 
  
 android.content.DialogInterface 
 ; 
 import 
  
 android.content.Intent 
 ; 
 import 
  
 android.os.Bundle 
 ; 
 import 
  
 android.util.Log 
 ; 
 import 
  
 com.google.android.gms.common.api.PendingResult 
 ; 
 import 
  
 com.google.android.gms.common.api.ResultCallback 
 ; 
 import 
  
 com.google.android.gms.tagmanager.Container 
 ; 
 import 
  
 com.google.android.gms.tagmanager.Container.FunctionCallMacroCallback 
 ; 
 import 
  
 com.google.android.gms.tagmanager.Container.FunctionCallTagCallback 
 ; 
 import 
  
 com.google.android.gms.tagmanager.ContainerHolder 
 ; 
 import 
  
 com.google.android.gms.tagmanager.TagManager 
 ; 
 /** 
 * 
 Displays 
 simple 
 splash 
 screen 
 while 
 GTM 
 container 
 is 
 loading 
 . 
 Once 
 the 
 container 
 is 
 loaded 
 , 
 * 
 launches 
 the 
 { 
 @link 
 MainActivity 
 } 
 . 
 */ 
 public 
 class 
  
 SplashScreenActivity 
 extends 
 Activity 
 { 
 private 
 static 
 final 
 long 
 TIMEOUT_FOR_CONTAINER_OPEN_MILLISECONDS 
 = 
 2000 
 ; 
 private 
 static 
 final 
 String 
 CONTAINER_ID 
 = 
 "GTM-XXXX" 
 ; 
 @Override 
 public 
 void 
 onCreate 
 ( 
 Bundle 
 savedInstanceState 
 ) 
 { 
 super 
 . 
 onCreate 
 ( 
 savedInstanceState 
 ); 
 setContentView 
 ( 
 R 
 . 
 layout 
 . 
 activity_splashscreen 
 ); 
 TagManager 
 tagManager 
 = 
 TagManager 
 . 
 getInstance 
 ( 
 this 
 ); 
 // 
 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 
 ); 
 PendingResult<ContainerHolder> 
 pending 
 = 
 tagManager 
 . 
 loadContainerPreferNonDefault 
 ( 
 CONTAINER_ID 
 , 
 R 
 . 
 raw 
 . 
 defaultcontainer_binary 
 ); 
 // 
 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 
 ); 
 // 
 Rest 
 of 
 the 
 Activity 
 definition 
 . 
 }

4. Getting Configuration Values from the Container

Once the container is loaded, you can retrieve configuration values using any of the Container.get <type> () methods. Configuration values are defined using Google Tag Manager's value collection variables. For example, the following method retrieves the latest color we've decided to use in for a UI element and returns it as an integer:

 /** 
  
 * 
  
 Returns 
  
 an 
  
 integer 
  
 representing 
  
 a 
  
 color 
 . 
  
 */ 
 private 
  
 int 
  
 getColor 
 ( 
 String 
  
 key 
 ) 
  
 { 
  
 return 
  
 colorFromColorName 
 ( 
 containerHolder 
 . 
 getContainer 
 (). 
 getString 
 ( 
 key 
 )); 
 }

This code does two things to retrieve the color name from the container:

Gets the Container from the ContainerHolder using ContainerHolder.getContainer() .
Gets the color value using Container.getString( key ) , where you have defined the key and value in the Google Tag Manager web interface.

5. Pushing Events and Values to the dataLayer

Google Tag Manager also provides a dataLayer , into which you can push information about your application that can be read in other parts of your application or used to fire tags you've configured in the Google Tag Manager web interface.

Pushing Values to the dataLayer

The dataLayer provides a layer of persistence that you can use to store key-value pairs you might want to use in other parts of your application, or as inputs to Google Tag Manager tags.

To push a value to the dataLayer , follow this pattern:

Get the DataLayer singleton:

DataLayer dataLayer = TagManager.getInstance(context).getDataLayer();

Push the event using DataLayer.push() :

 // Put the image_name into the data layer for future use. 
 TagManager 
 . 
 getInstance 
 ( 
 this 
 ). 
 getDataLayer 
 (). 
 push 
 ( 
 IMAGE_NAME_KEY 
 , 
  
 imageName 
 );

To get a value from the dataLayer , use DataLayer.get( key ) .

Pushing Events to the dataLayer

Pushing events to the dataLayer allows you to separate your application code from tags you might want to fire in response to those events.

For example, instead of hard-coding Google Analytics screenview tracking calls into your application, you could push screen events onto the dataLayer and define your tracking tags via the Google Tag Manager web interface. This gives you the flexibility to modify that tag, or add additional tags that respond to screen events, without updating your application code.

To push an event to the dataLayer , follow this pattern:

Get the DataLayer singleton:

DataLayer dataLayer = TagManager.getInstance(context).getDataLayer();

Push the event using DataLayer.pushEvent() :
```
dataLayer.pushEvent("openScreen", DataLayer.mapOf("screenName", screenName));
```
DataLayer.mapOf() is a utility method you can use to easily generate a map of key-value pairs that will update the dataLayer at the same time the event is pushed.

See a Code Snippet from the Sample Application

The following utility class demonstrates how to push events, like information about screens opening and closing in your app, on the dataLayer :

 package 
 com 
 . 
 google 
 . 
 android 
 . 
 tagmanager 
 . 
 examples 
 . 
 cuteanimals 
 ; 
 import 
  
 android.content.Context 
 ; 
 import 
  
 com.google.android.gms.tagmanager.DataLayer 
 ; 
 import 
  
 com.google.android.gms.tagmanager.TagManager 
 ; 
 /** 
 * 
 Utility 
 class 
 . 
 */ 
 public 
 class 
  
 Utils 
 { 
 private 
 Utils 
 () 
 { 
 // 
 private 
 constructor 
 . 
 } 
 /** 
 * 
 Push 
 an 
 "openScreen" 
 event 
 with 
 the 
 given 
 screen 
 name 
 . 
 Tags 
 that 
 match 
 that 
 event 
 will 
 fire 
 . 
 */ 
 public 
 static 
 void 
 pushOpenScreenEvent 
 ( 
 Context 
 context 
 , 
 String 
 screenName 
 ) 
 { 
 DataLayer 
 dataLayer 
 = 
 TagManager 
 . 
 getInstance 
 ( 
 context 
 ) 
 . 
 getDataLayer 
 (); 
 dataLayer 
 . 
 pushEvent 
 ( 
 "openScreen" 
 , 
 DataLayer 
 . 
 mapOf 
 ( 
 "screenName" 
 , 
 screenName 
 )); 
 } 
 /** 
 * 
 Push 
 a 
 "closeScreen" 
 event 
 with 
 the 
 given 
 screen 
 name 
 . 
 Tags 
 that 
 match 
 that 
 event 
 will 
 fire 
 . 
 */ 
 public 
 static 
 void 
 pushCloseScreenEvent 
 ( 
 Context 
 context 
 , 
 String 
 screenName 
 ) 
 { 
 DataLayer 
 dataLayer 
 = 
 TagManager 
 . 
 getInstance 
 ( 
 context 
 ) 
 . 
 getDataLayer 
 (); 
 dataLayer 
 . 
 pushEvent 
 ( 
 "closeScreen" 
 , 
 DataLayer 
 . 
 mapOf 
 ( 
 "screenName" 
 , 
 screenName 
 )); 
 } 
 }

6. Previewing, Debugging, and Publishing

Before publishing a version of your container, you'll want to preview it to make sure it works as intended. Google Tag Manager gives you the ability to preview versions of your container by generating links and QR codes in the web interface and using them to open your application. You can also enable a verbose logging mode to debug any unexpected behavior.

Previewing

To preview a version of your container, follow these steps:

Adding this preview Activity to your AndroidManifest file:

< ! 
 --  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 
>

Be sure to modify this line to include your application's package name:

<data android:scheme="tagmanager.c.com.google.android.tagmanager.examples.cuteanimals" />

Generate a preview link in the Google Tag Manager web interface
1. Sign in to Google Tag Manager
2. Select the container Versionto preview
3. Click the Previewbutton
4. Enter your application's package name and click Generate begin preview link
Use the generated link or QR Code to launch your application
You can exit preview mode by following a link generated by the Generate end preview linkoption in the web interface.

Debugging

If you need to troubleshoot your container implementation, enable verbose logging by calling 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 
 );

Publishing

After you've previewed your container and verified it's working as intended, you can publish your container . Your container configuration values, tags, and events will be live for users the next time their containers are refreshed. Learn more about refreshing containers .

Advanced Configuration

The following sections describe advanced configuration options you want to use to further customize your Google Tag Manager implementation.

Refreshing the Container

By default, your container becomes eligible to be refreshed every 12 hours. To manually refresh the container, use ContainerHolder.refresh() :

ContainerHolderSingleton.getContainerHolder().refresh();

This is an asynchronous call that will not return immediately. To reduce network traffic, refresh() may only be called once every 15 minutes, otherwise it will be a no-op.

See a Code Snippet from the Sample Application

 public 
  
 void 
  
 refreshButtonClicked 
 ( 
 @SuppressWarnings 
 ( 
 "unused" 
 ) 
  
 View 
  
 view 
 ) 
  
 { 
  
 Log 
 . 
 i 
 ( 
 TAG 
 , 
  
 "refreshButtonClicked" 
 ); 
  
 ContainerHolderSingleton 
 . 
 getContainerHolder 
 (). 
 refresh 
 (); 
  
 // 
  
 Push 
  
 the 
  
 "refresh" 
  
 event 
  
 to 
  
 trigger 
  
 firing 
  
 an 
  
 analytics 
  
 tag 
 . 
  
 TagManager 
 . 
 getInstance 
 ( 
 this 
 ). 
 getDataLayer 
 (). 
 push 
 ( 
 "event" 
 , 
  
 "refresh" 
 ); 
  
 // 
  
 Push 
  
 the 
  
 "custom tag" 
  
 event 
  
 to 
  
 trigger 
  
 firing 
  
 a 
  
 custom 
  
 function 
  
 call 
  
 tag 
 . 
  
 TagManager 
 . 
 getInstance 
 ( 
 this 
 ). 
 getDataLayer 
 (). 
 push 
 ( 
 "event" 
 , 
  
 "custom_tag" 
 ); 
  
 updateCategories 
 (); 
 }

Android v4 - Getting Started Stay organized with collections Save and categorize content based on your preferences.

Introduction

Before you Begin

Getting Started

1. Adding Google Tag Manager to your Project

2. Adding a Default Container File to your Project

3. Initializing Google Tag Manager

Creating a ContainerHolder Singleton

See a Code Snippet from the Sample Application

4. Getting Configuration Values from the Container

5. Pushing Events and Values to the dataLayer

Pushing Values to the dataLayer

Pushing Events to the dataLayer

See a Code Snippet from the Sample Application

6. Previewing, Debugging, and Publishing

Previewing

Debugging

Publishing

Advanced Configuration

Refreshing the Container

See a Code Snippet from the Sample Application

Android v4 - Getting Started