Android SDK - Installation and Usage

Summary:

This document contains instructions on installing and using Blue Triangle's software development kit (SDK) for Android.

• Example project in Github
• Supported Platforms
• Using the Analytics Library
  • Initializing the Tracker
  • Using Timers

Example Project in Github

For an example of how to use the Android SDK, please check out our example project in Github:  

https://github.com/blue-triangle-tech/btt-android-sdk

Supported Platforms

Include the following repository: 

        maven {
            url  "https://dl.bintray.com/bluetriangle/Blue-Triangle-SDK"
        }

SDK for Android is available on the following platforms.

Gradle:

implementation 'com.bluetriangle:analytics:[VERSION]'

Maven:

<dependency>
      <groupId>com.bluetriangle</groupId>
      <artifactId>analytics</artifactId>
      <version>[VERSION]</version>
      <type>pom</type>
</dependency>

Ivy:

<dependency org="com.bluetriangle" name="analytics" rev="[VERSION]">
      <artifact name="analytics" ext="pom"></artifact>
</dependency>

Using the Analytics library

Initializing the Tracker

The Tracker is a singleton instance that is responsible for sending timers to Blue Triangle. Before any timers can be tracked, the Tracker needs to be initialized. The best place to do this in the Android Application. In the Application, the tracker can be initialized via the init static methods. If a site ID is not set during the initialization, it will attempt to look up the site ID via the application's String resources with a name btt_site_prefix as shown below. If a tracker URL is not provided, the default tracker URL will be used.

<string name="btt_site_prefix" translatable="false">BTT_SITE_PREFIX</string>

// init with all defaults, use site ID in string resources file
Tracker.init(getApplicationContext());
// init with given site ID
Tracker.init(getApplicationContext(), "BTT_SITE_PREFIX");
tracker.trackCrashes();

Using Timers

Timers are simple data objects that contain the associated times, fields related to the timer instance, and methods to start, mark interactive, and end a timer. Fields associated with the timer such as page name, traffic segment, brand value, etc can be set on the timer via convenience constructors and methods. Associated fields can be set anytime during the lifetime of the timer until submitted to the Tracker.

// create and start a timer
final Timer timer = new Timer("Page Name", "Traffic Segment Name").start();

// do work

// optionally, mark the timer as interactive
timer.interactive();

// maybe set a field
timer.setCartValue(99.99);

// do some more work

// end the timer and submit
timer.end().submit();

// or end the timer, set fields such as brand value, and finally submit the timer.

timer.end();
timer.setBrandValue(99.99);
timer.submit();

Timers implement Parcelable to allow timers to be passed via Bundle such as between activities in an Intent.

// MainActivity.java
final Timer timer = new Timer("Next Page", "Android Traffic").start();
final Intent intent = new Intent(this, NextActivity.class);
intent.putExtra(Timer.EXTRA_TIMER, timer);
startActivity(intent);

// NextActivity.java
final Timer timer = getIntent().getParcelableExtra(Timer.EXTRA_TIMER);
timer.end().submit();

When a timer is submitted to the tracker, the tracker sets any global fields such as site ID. Additional global fields may be set as needed and applied to all timers. The timer's fields are then converted to JSON and sent via HTTP POST to the configured tracker URL.