Adding Tealium to Your Android App

Adding Tealium to Your Android App

by Community Manager on ‎01-04-2017 01:25 PM - edited 4 weeks ago (3,616 Views)

This guide shows how to add Tealium to your Android Mobile or Android TV app to track user activity.

Table of Contents Placeholder

Requirements

  • Android Studio
  • Android API Level 9 and higher (Gingerbread/2.3)

For use with iQ Tag Management:

For use with Universal Data Hub:

Get the Code

The code for the Tealium Android library can be found on Github. You must download and install the library before proceeding.

Cloning the library, instead of downloading, will make it easier to update to future releases.

Installation

The current version of the Tealium Android library is 5.3.1, released on 08/15/2017


Tealium uses Maven to install and manage dependencies.

Add the Tealium Maven URL to your project root build.gradle file:

allprojects {
repositories {
jcenter()

maven {
url "http://maven.tealiumiq.com/android/releases/"
}
}
}

Add the Tealium dependency to your project module build.gradle file:

dependencies {
compile 'com.tealium:library:5.3.1'
}

Add to Project Manually

You can also add the dependency manually.

Add flatDir to your project root build.gradle file:

allprojects {
    repositories {
        jcenter()
        flatDir {
            dirs 'libs'
        }
    }
}

Add tealium-5.x.x.aar to <PROJECT_ROOT>/<MODULE>/libs.

Add the Tealium library dependency to your build.gradle file: 

dependencies {
    compile(name:'tealium-5.3.1', ext:'aar')

Initialization

The Tealium instance must be configured with the following parameters before it will begin tracking:

  • account - the name of your account
  • profile - the name of your profile
  • environment - one of "qa" or "prod"
  • datasource - (optional) the data source key from UDH
  • instance - a unique name for your instance (multiple instances are supported)

Add the following code to the onCreate method in the Application sub-class:

Tealium.Config tealConfig = Tealium.Config.create(application,
"ACCOUNT",
"PROFILE",
"ENVIRONMENT");
// Currently optional - add a 6 character alphanumeric data source ID.
// If you have not been given a data source ID, you can omit this. Note that this is a mock value
tealConfig.setDataSourceId("abc123");
/* setForceOverrideLogLevel - optional - forces the log level to be set to one of "dev", "qa", "prod" or "silent".
* Overrides remote publish setting. Remote publish settings used if omitted. */
tealConfig.setForceOverrideLogLevel("prod");
Tealium.createInstance("INSTANCE", tealConfig);

Tracking Views

Every time a user opens or changes a screen in the app a tracking call should be made.  A view is tracked by calling trackView() with two parameters: the name of the screen and (optionally) contextual view data. 

The screen name will be populated in the event data as the screen_title variable.

Map<String, Object> data = new HashMap<>(1);
data.put("someKey", "someValue");

Tealium.getInstance("INSTANCE").trackView("screenName", data);

Tracking Events

All non-view activity should be tracked as an event. This is easily done by calling trackEvent() with two parameters: an event name and (optionally) contextual event data.

The event name will be populated in the event data as the tealium_event variable.

Map<String, Object> data = new HashMap<>(1);
data.put("someKey", "someValue");

Tealium.getInstance("INSTANCE_NAME").trackEvent("someEvent", data); 

Overriding The Default Log Level

By default, the amount of logging performed by the Tealium library is controlled by the remote publish settings. Sometimes, however, this is not convenient for developers who may not have access to Tealium iQ to change the settings.

With release 5.3.1 of the Tealium library, we now support overriding the log level locally at initialization time. To set a specific log level, use the following snippet:

Tealium.Config tealConfig = Tealium.Config.create(application,
"ACCOUNT",
"PROFILE",
"ENVIRONMENT");

/* Options are:
* "dev" (warnings, errors, info)
* "qa" (errors & warnings only)
* "prod" (errors only)
* "silent" (no logging, but may produce a couple of lines of log output in cases where the config object hasn't yet been initialized)
*/
tealConfig.setForceOverrideLogLevel("dev"); // forces the log level to be set to dev

v5.1.0 and above - CookieManager is enabled by default.  
v5.0.4 and below - CookieManager is disbabled by default. Enablement of CookieManager is required for if using Tag Management

If you have enabled Tag Managements in your mobile profile then the following code can be added to activate cookie management. This code allows the Tag Management Webview to:

This must be placed after the initialization statement.

config.getEventListeners().add(createCookieEnablerListener());

private static WebViewCreatedListener createCookieEnablerListener() {
return new WebViewCreatedListener() {
@Override
public void onWebViewCreated(WebView webView) {
final CookieManager mgr = CookieManager.getInstance();

// Accept all cookies
mgr.setAcceptCookie(true);

if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.LOLLIPOP) {
mgr.setAcceptThirdPartyCookies(webView, true);
}

if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.HONEYCOMB_MR1) {
CookieManager.setAcceptFileSchemeCookies(true);
}

Log.d(TAG, "WebView " + webView + " created and cookies enabled.");
}
};
}

Additional Resources