Tealium for Java

Tealium for Java

by on ‎09-19-2016 08:51 AM - edited 4 weeks ago by Community Manager (830 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

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  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.0.1</version>

Initialization

Once the Tealium 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 UDH
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
Map<String, Object> data = new HashMap<>(2);
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) Map<String, Object> of additional data source keys and values

optional_callback

Function

(Optional) Object conforming to the Tealium call back interface
// Event attributes
Map<String, Object> data = new HashMap<>(2);
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) Map<String, Object> of additional data source keys and values

optional_callback

Function

(Optional) Object conforming to the Tealium call back interface
// Event attributes
Map<String, Object> data = new HashMap<>(2);
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 map <String,Object> ["key":"value"]
Map<String, Object> data = new HashMap<>();
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
Map Of type <String,Object> ["key1", "key2"]
Map<String,Object> 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