BurtTracker is an Android library that enables sending tracking data to Burt’s services.
BurtTracker requires Android 2.3.3+ (10), Gingerbread MR1.
BurtTracker is distributed in a JAR file. Download the JAR and add it to the Android project. Make sure it is included in the build script.
A prerequisite for using the BurtTracker is that the application requires permission to use the internet as specified in the manifest file.
BurtTracker represents the entry point to the library. An instance of this class is configured with a tracking key obtained from Burt. The tracking key attributes and identifies the traffic source. Additionally, the BurtTracker configures whether debugging is enabled, etc. A single instance is meant to be shared throughout the lifetime of the app invocation.
From the BurtTracker one or more instances of ScreenTracker are created to track views. Most often the life cycle of a view corresponds to that of an activity in the app. Furthermore, in many cases, a view can be thought of as a page view in terms of web tracking. The SDK does not dictate any specific model and depending on the structure and flow of your specific app you may want or need to define a view differently. In general, we recommend to try to keep only one ScreenTracker started simultaneously. We urge you to seek help from your Burt representative when considering the model for your specific use case.
First, the BurtTracker has to be initialized. It is recommended to do this during the initialization of the app in such a way that subsequent activities can access the instance.
import com.burtcorp.sdk.*;
// ...
BurtTracker burtTracker = new BurtTracker(getApplicationContext(), new BurtTrackingOptions("TRACKINGKEY"));For every view you want to track, create and start a screenTracker:
ScreenTracker screenTracker = burtTracker.createScreenTracker("frontpage");
screenTracker.start();
// Or use this equivalent shorthand for creating and starting a screenTracker
ScreenTracker screenTracker = burtTracker.track("frontpage");The argument "frontpage" passed to BurtTracker#createScreenTracker (or BurtTracker#track) is the content ID of the view. It is meant to uniquely identify a URI to the content. If there is a web page corresponding to the same content, we recommend setting the content ID to that URL, e.g. "http://example.org/frontpage", in order to make analysis across multiple sources of tracking easier.
If you are using a release prior to version 0.2.0, you can safely ignore the rest of this section.
When a ScreenTracker is started it will perform periodical activities in the background. For example, it will send requests to Burt with updates to the view. It is done without any interaction to the ScreenTracker until the view ends.
The end of a view is indicated by stopping the ScreenTracker:
screenTracker.stop();The SDK measures the total duration and active duration of views. The total duration is simply the duration between starting and stopping a ScreenTracker. The active duration is meant to model the duration during which the user is actively engaged with the content. The model keeps a state whether the screen is considered active or inactive to attribute time to the active duration when appropriate.
The app must indicate to the ScreenTracker when the session becomes active (e.g. when the user scrolls the content of an activity or causes a touch event) or becomes inactive (e.g. when the user switches to another app) in order for the SDK to update the activity state. Two methods are used to indicate these events; #signalUserActive and #signalUserInactive.
When a screen starts, it will initially be inactive. If none of these methods are called before stopping the screen the active duration will be zero.
When #signalUserActive is called, the SDK will start to attribute time to active duration. This method must be called continuously as long as user interactions are detected to extend the active duration. Once #signalUserActive has not been called for 60 seconds a timeout will be reached and the screen will be considered inactive. At this point, the active duration will also be compensated to not include the time since the last indication of user activity.
When #signalUserInactive is called the user is considered inactive and active duration will not be attributed any time from that point in time until the next call to #signalUserActive.
Several cycles of active and inactive states are allowed within the same screen. The following gives an example time line for a screen where the user has clicked a link to an article activity:
screenTracker.start()screenTracker.signalUserActive()screenTracker.signalUserInactive()screenTracker.signalUserActive()screenTracker.signalUserActive()screenTracker.stop()A more in depth example of the implementation of the screen tracker life cycle can be found in Example implementation.
Associating additional metadata to the view is done via annotations. See the glossary for more info.
For example, if the view corresponds to an article and you want to associate the author who wrote it you annotate the information, like so:
screenTracker.annotate("content", "author", "Sam Smith");#annotate must be called after the ScreenTracker is started, but before it is stopped.
The arguments to ScreenTracker#annotate are, in order, the scope, name and value of the annotation. The name identifies what data the value is and the scope is a logical grouping of related annotations. Talk to your Burt representative to get further guidance on setting up appropriate anntoations, scope and name attributes.
Profiles are fetched asynchronously and the user has to provide a ProfilesCallback implementation in order to handle the result:
burtTracker.profile(new ProfilesCallback() {
@Override
public void onComplete(Profile profile) {
// use profile
}
@Override
public void onError(BurtException exception) {
if (exception.getClass() == RetriableException.class) {
// retry and it may work
} else if (exception.getClass() == BadInputException.class) {
// change the input and try again
} else if (exception.getClass() == UnknownException.class) {
// something went wrong, contact us
}
}
});The view tracking example above describes the most basic setup, but the library allows you to tweak a few parameters and can give you more fine grained control over the tracking.
The BurtTrackerOptions class that is used to construct the tracker exposes a few properties, which are described in detail below. A sample test setup could look like
BurtTrackerOptions burtTrackerOptions = new BurtTrackerOptions("tracking-key");
burtTrackerOptions.debug(true);
burtTrackerOptions.userTracking(true);
burtTrackerOptions.protocol(BurtTrackerOptions.Protocol.HTTPS);
BurtTracker burtTracker = new BurtTracker(this, burtTrackerOptions);Using the snippet above, you’d get a tracker that logs requests and warnings to the console, allows user tracking and sends the requests over https.
The actual screen tracking can also expose a more flexible interface, which allows you to add cloud keys (see the glossary for more info) and gives you control over when to start tracking. Adding cloud keys can be done by
ScreenTracker screenTracker = burtTracker.createScreenTracker("view-id");
screenTracker.addCloudKey("a-cloud-key");
screenTracker.addCloudKey("another-cloud-key");
screenTracker.start();Note that all cloud keys must be added prior to starting the screen tracker. Until start() is called, the screen tracker will be inactive and not make any requests to Burt’s servers. While cloud keys must be added before start(), annotations and connections can be added at any time. Note that they won’t be sent until the after screen tracker is started.
BurtTracker(Context context, BurtTrackerOptions burtTrackerOptions)track(String viewId)createScreenTracker(String viewId)profiles(ProfilesCallback callback)BurtTrackerOptions(String trackingKey)trackingKey(String trackingKey)userTracking(Boolean userTracking)debug(Boolean debug)protocol(BurtTrackerOptions.Protocol protocol)annotate(String scope, String name, String value)connect(String scope, String name, String value)addCloudKey(String cloudKey)start()stop()signalUserActive()signalUserActive(boolean persistent)signalUserInactive()BurtTracker(Context context, BurtTrackerOptions burtTrackerOptions)Constructs a BurtTracker with burtTrackerOptions, which specify configuration parameters like tracking key, debug mode, etc.
In order to provide the best performance and let the SDK to operate as efficiently as possible a single instance of this class shall be shared when possible.
track(String viewId)Starts and returns a new ScreenTracker with the id viewId.
createScreenTracker(String viewId)Initiates and returns a screen tracker which is not started.
profilesFetches the Profile and uses it as an argument in the ProfilesCallback implementation provided.
BurtTrackerOptions(String trackingKey)Initiates a BurtTrackerOptions with a trackingKey.
trackingKey(String trackingKey)Sets the tracking key.
userTracking(Boolean userTracking)Sets the user tracking flag. Profiles will not be usable without this option.
debug(Boolean debug)Sets the debug mode flag. Useful when developing.
protocol(BurtTrackerOptions.Protocol)Sets the protocol for communication with Burt’s API.
annotate(String scope, String name, String value)Annotates the view with custom data.
connect(String scope, String name, String value)Adds a connection to the view.
addCloudKey(String cloudKey)Adds a cloud key to the screen tracker.
start()Start the screen tracker and start sending data to Burt’s servers.
Once started, a screen tracker will perform periodical background activities that use the network, regardless of whether the app is in the foreground or not.
If you have chosen to not stop the tracking upon onPause or onStop you may want to implement logic to stop the tracker anyway after a timeout is reached, to prevent prolonged battery drain.
stop()Added in v0.2.0
Stop the screen tracker. After this method has been called it cannot be started again and further interaction with the ScreenTracker instance, e.g. #signalUserActive and #annotate will be ignored.
signalUserActive()Added in v0.2.0
Shorthand for calling signalUserActive(false). See signalUserActive(boolean persistent).
signalUserActive(boolean persistent)Added in v0.2.0
Indicate that the user is active. From the point that this method is called the user is considered active for one minute or persistently, depending on the value of persistent.
When persistent is false and if no further calls are received within one minute the screen is automatically transitioned to inactive. For each further call within one minute the timeout is reset. Thus, a screen will stay active as long as a call occurs at least every minute. We recommend using this mode when continuous interactions are required to consider the screen active. For example, the following events typically indicate user activity and are appropriate times to indicate activity:
Depending on the layout and structure of your particular app some of these may not apply or there may be additional events.
When persistent is true the active state remains until either #signalUserActive(false), #signalUserInactive() or #stop() is called. We recommend using this mode when the screen is to be considered active regardless of continuous interactions from the user. For example, when a user starts a video clip within the screen it may be desired to use this mode so that the complete duration of the video is attributed as active. In other cases, the mere presence of a screen may be sufficient to indicate the user is actively engaged.
Consult your Burt representative for guidance on working with these modes and what events may be appropriate for your app.
signalUserInactive()Added in v0.2.0
Indicate that the user is inactive, i.e. absent from interaction with the content. This method shall be called when the user has triggered an event that is a clear indication of the user being absent. Here are some examples of appropriate events:
getId()Returns the profile’s id as a String.
getSegments(String scope, String name, String value)Returns the segments belonging to the profile as a List<String>.
onComplete(Profile profile)The implementation of this method is called when the Profile has been fetched.
This section describes an example implementation of the SDK. The example assumes that you are using version 0.2 or later. The proposed example scenario is an app that present news articles. The example shows how an activity ArticleActivity implements screen tracking.
First, the ArticleActivity class looks like this:
public class ArticleActivity extends AppCompatActivity {
private BurtTracker burtTracker;
private BurtEventService burtEventService;
protected ScreenTracker screenTracker;
protected boolean stopOnPause;
protected View view;
boolean shouldExecuteOnResume;
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
// For the purpose of the example, the BurtTracker is created
// for each instance of the activity, but it is highly
// recommended to share the same instance between all screens
// to be tracked. See BurtTracker API documentation.
BurtTrackerOptions burtTrackerOptions = new BurtTrackerOptions("TESTKEY12345");
burtTrackerOptions.debugging(true);
burtTrackerOptions.protocol(BurtTrackerOptions.Protocol.HTTP);
this.burtTracker = new BurtTracker(this, burtTrackerOptions);
trackScreen();
shouldExecuteOnResume = false;
}
@Override
public void onPause(){
super.onPause();
stopTracking();
}
@Override
public void onStop(){
super.onStop();
stopTracking();
}
@Override
public void onResume(){
super.onResume();
if (shouldExecuteOnResume) {
trackScreen();
} else {
shouldExecuteOnResume = true;
}
}
@Override
public void onDestroy(){
super.onDestroy();
stopTracking();
}
protected void startTracking() {
// getArticleUrl is assumed to return a string with the URL to
// the current article
screenTracker = this.burtTracker.createScreenTracker(getArticleUrl());
screenTracker.start();
burtEventService = new BurtEventService(screenTracker, "ArticleActivity");
view.setOnClickListener(burtEventService);
view.setOnFocusChangeListener(burtEventService);
view.setOnTouchListener(burtEventService);
view.getViewTreeObserver().addOnScrollChangedListener(burtEventService);
// getArticleSection is assumed to return a string naming the
// section that the current article belongs to
screenTracker.annotate("article", "section", getArticleSection());
}
private void stopTracking() {
screenTracker.stop();
view.getViewTreeObserver().removeOnScrollChangedListener(burtEventService);
}
}With this implementation a screen will be started for the first time via the onCreate callback. If the activity is paused, causing onPause to be called, the screen will stop. If the activity is then resumed, causing onResume to be called, a new screen will be tracked. The screen is finally stopped in the onDestroy callback.
You will notice that several events, such as onTouch, onClick, onFocusChange, onScrollChanged and onWindowFocusChanged are delegated to an instance of BurtEventService.
Click, touch and scroll are good indicators of user activity, thus #signalUserActive is called. The onFocusChange and onWindowFocusChange events, depending on whether the focus is gained or lost, are also indicators. Therefor, #signalUserActive and #signalUserInactive are called for the respective case. The implementation of the BurtEventService looks like this:
import android.view.View;
import android.view.View.*;
import android.view.ViewTreeObserver.*;
import com.burtcorp.sdk.ScreenTracker;
public class BurtEventService implements OnClickListener,
OnFocusChangeListener,
OnTouchListener,
OnScrollChangedListener,
OnWindowFocusChangeListener {
private final ScreenTracker screenTracker;
private final String scope;
public BurtEventService(final ScreenTracker screenTracker) {
this.screenTracker = screenTracker;
}
@Override
public void onClick(View view) {
screenTracker.signalUserActive();
}
@Override
public void onFocusChange(View view, boolean hasFocus) {
if (hasFocus) {
screenTracker.signalUserActive();
} else {
screenTracker.signalUserInactive();
}
}
@Override
public boolean onTouch(View view, MotionEvent motionEvent) {
screenTracker.signalUserActive();
return false;
}
@Override
public void onScrollChanged() {
screenTracker.signalUserActive();
}
@Override
public void onWindowFocusChanged(boolean hasFocus) {
if (hasFocus) {
screenTracker.signalUserActive();
} else {
screenTracker.signalUserInactive();
}
}
}