Tealium for Java

Tealium for Java

by jason_koo on ‎09-19-2016 08:51 AM - edited a week ago by Community Manager (1,097 Views)

This guide shows how to add Tealium to your Java application to track event activity.  Before you begin, here's a video introduction to the platform:

Table of Contents Placeholder

Installation

Requirements

 Before proceeding, ensure you have satisfied the following requirements:

Get the Code

The code for the Tealium Java library is stored in Github. You must retrieve the code to get started.

We recommend cloning the library (instead of downloading) to make it easier to update to future releases.

Code Setup

The type signatures of some of the methods have changed. Event data used to be a Map<String, Object> type, but has changed to be a Udo (universal data object) type. Because event data must follow a specific format where each value is eather a String or List<String>, a more specific type is helpful. (See the Universal Data Object Guide for the formatting details.)

The new Udo type implements the Map<String, Object> interface, and therefore can be used wherever a Map<String, Object> can. Although still usable, the previous methods using Map<String, Object> have been deprecated and should be switched out for the updated version since they will likely be dropped in a future update.

Import all of the .java files from the src/main/java/com/tealium directory, then add this code:

import com.tealium.*

Using Maven

Make the following changes to your pom.xml file:

Add the repository:

<repository>
<id>maven-tealium</id>
<url>s3://maven.tealiumiq.com/java/releases/</url>
</repository>

Add the dependency:

    <groupId>com.tealium</groupId>
    <artifactId>java</artifactId>
    <version>1.3.0</version>

Initialization

Once the files are added to your project you are ready to start coding. The Tealium instance must be invoked with the following parameters before you can begin tracking:

  • account - the name of your account
  • profile - the name of the profile within your account
  • environment - (optional) one of "qa" or "prod"
  • datasource - (optional) the data source key from your Universal Data Hub account
Tealium tealium = new Tealium.Builder("ACCOUNT", "PROFILE")
.setEnvironment("prod")
.setDatasource("DATASOURCE")
.build();

Tracking

Once the Tealium instance has been defined you can begin tracking events with the method track(), which takes the following parameters:

  • eventName (required) - a name to identify the event
  • eventData (optional) - an object with event attributes as key/value pairs
  • callback (optional) - a function to be called when the track() method completes

 

// Set event attributes
Udo data = new Udo();
data.put("user_id", "0123456789");
data.put("email_address", "user@example.com");

// With optional callback
DispatchCallBack callBack = new DispatchCallBack(){
public void dispatchComplete(boolean success, String encodedURLString, String error){
// Callback handling
System.out.println("Dispatch successful: " + String.valueOf(success));
}
}
// Tracking a login event
tealium.track("user_login", data, callBack);

Watch this video for a quick summary of the installation steps:

 

Function Definitions

Tealium.Builder()

Instantiate a Tealium object.

Tealium.Builder(account, profile, environment).build()
Parameters Type Description Example Value
account String Tealium account name

"companyxyz"

profile

String

Tealium profile

"main" 

environment 

String

Tealium environment identifer

"prod"

datasource

String

Tealium data source key from UDH

"abc123"

// Init Tealium
Tealium teal = new Tealium.Builder('ACCOUNT', 'PROFILE')
.setEnvironment("ENVIRONMENT")
.setDatasource("DATASOURCE")
.build();

track()

Convenience track call.

track(eventName)
Parameters Type Description
eventName String

Name of event (becomes the event_name event attribute value)

tealium.track("user_login");

 

Convenience track call for events that can optionally include additional data and a callback.

track(eventName, eventData, [callback])
Parameters Type Description
eventName String

Name of event (becomes the event_name event attribute value)

eventData

Map Object

(Optional) Udo of additional data source keys and values

optional_callback

Function

(Optional) Object conforming to the Tealium call back interface
// Event attributes
Udo data = new Udo();
data.put("user_id", "0123456789");
data.put("email_address", "user@example.com");

// With optional callback
DispatchCallBack callBack = new DispatchCallBack(){

public void dispatchComplete(boolean success, String error) {
// Callback code here
}

}
tealium.track("user_login", data, callback);

 

Primary track call for all events associated data including optional data and a callback.

track(eventType, eventName, eventData, [callback])
Parameters Type Description
eventType String

Type of event (activity, conversion, derived, interaction, view) - Default is activity.

eventName String

Name of event (becomes the event_name event attribute value)

eventData

Map Object

(Optional) Udo of additional data source keys and values

optional_callback

Function

(Optional) Object conforming to the Tealium call back interface
// Event attributes
Udo data = new Udo();
data.put("user_id", "0123456789");
data.put("email_address", "user@example.com");

// With optional callback
DispatchCallBack callBack = new DispatchCallBack(){

public void dispatchComplete(boolean success, String error) {
// Callback code here
}

}
tealium.track("activity", "user_login", data, callback);

getDataManager()

Fetch the DataManager object. The Data Manager processes call time data and handles persistent data.

getDataManager()
Returns Description Example Value
DataManager Instance of the Tealium Data Manager object NA
DataManager dm = tealium.getDataManager()

addPersistentData()

Use the DataManager to make data available across multiple app sessions.

addPersistentData(map<String, Object>)
Parameters Description Example Value
data Required map to add to the existing persistent udo ["key":"value"]
Udo data = new Udo();
data.put("aKey", "aValue")
tealium.getDataManager().addPersistentData(data); 

deletePersistentData()

Use the DataManager to delete previously persisted data by providing a list of keys to delete.

deletePersistentData(array<String>)
Parameters Description Example Value
keys Array of Keys as strings ["key1", "key2"]
List<String> list = new List<>();
list.append("key_to_delete");
tealium.getDataManager().deletePersistentData(list);

getPersistentData()

Use the DataManager to retrieve data that has been persisted.

getPersistentData()
Returns Description Example Value
Udo Udo of persistent data ["key1", "key2"]
Udo persistentData = tealium.getDataManager().getPersistentData()

getSessionId()

Use the DataManager to fetch the current session ID. A session ID is created on initialization of the Tealium object.

getSessionId()
Returns Description Example Value
String String representation of a timestamp in milliseconds "1473371215123"
tealium.getDataManager().getSessionId() 

resetSessionId()

Use the DataManager to reset the session ID. For use when needing to start a new session other than at app start time.

resetSessionId()
Returns Description Example Value
String New String representation of a timestamp in milliseconds that will be added to all dispatches for the remainder of the current session. The returned String is for monitoring convenience as it is automatically added to the volatile data store when this method is called. "1473371215123"
tealium.getDataManager().resetSessionId()

  

ChangeLog

1.1.0 - Current

1.0.0 - 1.0.1