Tracklytics

Tracklytics is an annotation based analytic tools aggregator with using AOP to track events and crashes. It basically collects all analytic/tracking tools together and provide a simple and clean solution without polluting your code base.

Common problems are for the analytics tools are;

Polluted code, more tracking code than the business code
Too many analytic tools to track events
Hard to maintain

Tracklytics moves all these problems to an individual module which has handler for each analytic tool. By using aspect oriented programming, all tracking codes will be added to your business code during the compile time, which means that you don't need to worry about performance.

Tracklytics solution

Moves all analytics/tracking code and add them in compile time.
Provides a debugging monitor tool to visualise all occured events.

Usage

@TrackEvent("EventName")

Track an event by using event name.

@TrackEvent("title") 
public void trackNoValues() {
  // something
}

@Attribute("key")

Track method parameters as key/value pair.

@TrackEvent("eventName") 
public void trackMe(@Attribute("eventKey") String eventValue) {
  // something
}

Attribute has now a default result. Default result will be used regardless of the parameter or return value

@Attribute(value="Login", defaultResult="Success")

Track event with return value. By adding @Attribute to the method, it will add the returning value to the event key/value pairs.

@TrackEvent("eventName") 
@Attribute("eventKey")
public String trackMe() {
  // something
  return "eventValue";
}

Track event with both return value and parameters.

@TrackEvent("eventName") 
@Attribute("eventKey1")
public String trackMe(@Attribute("eventKey2") String eventValue2) {
  // something
  return "eventValue1";
}

@Track

For single tracking operation, you can use Track.

@Track(eventName="Foo", attributeKey="Login", attributeValue="Success")
void something(){}

@TrackFilter(TRACKER_TYPE1, TRACKER_TYPE2)

Sometimes you may want to track an event for a specific tracker or trackers. Filter will handle it for you. For example, below example: Only google analytics will track the event.

@TrackFilter(TrackerType.MIXPANEL)
@TrackEvent("title") 
public void trackEventFilter() {
  // something
}

@Tracklytics

Before using tracklytics, you must initialize it. Create a method which returns Tracker type and initialize all your trackers. All dependencies and other complex logic will be added/handled by tracklytics.

class DefaultApplication {

  @Tracklytics(TrackerAction.INIT) 
  public Tracker init() {
    return Tracker.init(
        new MixPanelTrackingAdapter(context, "API_KEY"),
        new FabricTrackingAdapter(context)
    );
  }
}

or for custom initialization, override onCreate method of TrackingAdapter.

  new FabricTrackingAdapter(context) {
    @Override public void onCreate(Context context){
      Fabric.with(context, new Answers());
      Fabric.with(context, new Crashlytics());
      .. more
    }
  }

For the best usage, use start and stop functions in your activities onStart/onStop or on any other entry/exit points

class MainActivity extends Activity {

  @Tracklytics(TrackerAction.START) 
  @Override void onStart(){
  }
  
  @Tracklytics(TrackerAction.STOP) 
  @Override void onStop(){
  }
  
}

Install

Add the following code block to in your app/build.gradle. Also have some issues to move all related fabric stuff to the tracklytics module. Because of that you need to add it to the classpath.

buildscript {
  repositories {
    jcenter()
    maven { url "https://oss.sonatype.org/content/repositories/snapshots/" }
    maven { url 'https://maven.fabric.io/public' }
  }
  dependencies {
    classpath 'io.fabric.tools:gradle:1.+'
    classpath 'com.orhanobut.tracklytics:tracklytics-plugin:0.25-SNAPSHOT'
  }
}

apply plugin: 'com.android.application'
apply plugin: 'com.orhanobut.tracklytics'

Enable the trackers that you want to use, as default they are enabled. Only enabled tracker's dependencies will be added to the project.

  tracklytics {
    mixpanel = true
    fabric = true
  }
  startTracklytics.execute()

Fabric

Fabric key should be added to your manifest file in order to use it.

<meta-data
  android:name="io.fabric.ApiKey"
  android:value="YOUR_FABRIC_KEY"
/>

Event Debugging Monitor

To be able to use debugging monitor, you need to inject it in the activity class.

 TracklyticsDebugger.inject(this);

By clicking "hand" icon, monitor will be displayed and each event will be updated in the list.

Debugging monitor displays

each event for each tracker
an option to remove all
filter option to select tracker, time and keyword (in progress)

Add custom tracker

You can always add another tracker by using TrackingAdapter.

Currently available tools:

Fabric (Crashlytics, Answers)
Mixpanel

##TODO

put the artifacts into the release repository and minify install part
find a solution for fabric
add more analytic tools

Licence

Copyright 2015 Orhan Obut

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

   http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

lreuven / tracklytics