This document describes how to get started using the Piwik Tracking SDK for Android. Piwik is the leading open source web analytics platform that gives you valuable insights into your website's visitors, your marketing campaigns and much more, so you can optimize your strategy and experience of your visitors.

Integrating Piwik into your Android app

1. Install Piwik
2. Create a new website in the Piwik web interface. Copy the Website ID from "Settings > Websites".
3. Include the library
4. Initialize Tracker.
5. Track screen views, exceptions, goals and more.
6. Advanced tracker usage

Add this to your apps build.gradle file:

compile 'org.piwik.sdk:piwik-sdk:0.0.3'

You can simply extend your application with a PiwikApplication class. This approach is used in our demo app.

Developers could manage the tracker lifecycle by themselves. To ensure that the metrics are not over-counted, it is highly recommended that the tracker be created and managed in the Application class.

import java.net.MalformedURLException;

public class YourApplication extends Application {
    private Tracker mPiwikTracker;

    public synchronized Tracker getTracker() {
        if (mPiwikTracker != null) {
            return mPiwikTracker;
        }

        try {
            mPiwikTracker = Piwik.getInstance(this).newTracker("http://your-piwik-domain.tld/piwik.php", 1);
        } catch (MalformedURLException e) {
            Log.w(Tracker.LOGGER_TAG, "url is malformed", e);
            return null;
        }

        return piwikTracker;
    }
    //...
}

Don't forget to add application name to your AndroidManifest.xml file.

    <application android:name=".YourApplication">
        <!-- activities goes here -->
    </application>

To send a screen view set the screen path and titles on the tracker

public class YourActivity extends Activity {
    @Override
    public void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        ((YourApplication) getApplication()).getTracker()
            .trackScreenView("/your_activity", "Title");
    }
}

To collect data about user's interaction with interactive components of your app, like button presses or the use of a particular item in a game use [trackEvent](http://piwik.github.io/piwik-sdk-android/org/piwik/sdk/Tracker.html#trackEvent(java.lang.String, java.lang.String, java.lang.String, java.lang.Integer)) method.

((YourApplication) getApplication()).getTracker().trackEvent("category", "action", "label", 1000)

If you want to trigger a conversion manually or track some user interaction simply call the method trackGoal. Read more about what is a Goal in Piwik.

((YourApplication) getApplication()).getTracker().trackGoal(1, revenue);

To track a custom name-value pair assigned to your users or screen views use [setVisitCustomVariable](http://piwik.github.io/piwik-sdk-android/org/piwik/sdk/Tracker.html#setVisitCustomVariable(int, java.lang.String, java.lang.String)) and [setScreenCustomVariable](http://piwik.github.io/piwik-sdk-android/org/piwik/sdk/TrackMe.html#setScreenCustomVariable(int, java.lang.String, java.lang.String)) methods. Those methods have to be called before a call to trackScreenView. More about custom variables on piwik.org.

Tracker tracker = ((YourApplication) getApplication()).getTracker();
tracker.setVisitCustomVariable(2, 'Age', '99');
tracker.trackScreenView(new TrackMe().setScreenCustomVariable(2, 'Price', '0.99'), '/path');

To track the number of app downloads you may call the method trackAppDownload This method uses SharedPreferences to ensures that tracking application downloading will be fired only once.

((YourApplication) getApplication()).getTracker().trackAppDownload();

Piwik provides ecommerce analytics that let you measure items added to carts, and learn detailed metrics about abandoned carts and purchased orders.

To track an Ecommerce order use trackEcommerceOrder method. orderId and grandTotal (ie. revenue) are required parameters.

Tracker tracker = ((YourApplication) getApplication()).getTracker();
EcommerceItems items = new EcommerceItems();
items.addItem("sku", "product", "category", 200, 2);
items.addItem("sku", "product2", "category2", 400, 3);
// grandTotal, subTotal, tax, shipping, discount, EcommerceItems
tracker.trackEcommerceOrder("orderId", 10000, 7000, 2000, 1000, 0, items);

The base method for any event is track You can create your own objects, set the parameters and send it along.

TrackMe trackMe = new TrackMe()
trackMe.set...
/* ... */
Tracker tracker = ((YourApplication) getApplication()).getTracker();
tracker.track(trackMe);

The tracker by default will dispatch any pending events every 120 seconds.

If a negative value is used the dispatch timer will never run, a manual dispatch must be used:

        
    Tracker tracker = ((YourApplication) getApplication()).getTracker();
    tracker.setDispatchInterval(-1);
    // Track exception
    try {
        revenue = getRevenue();
    } catch (Exception e) {
        tracker.trackException(e, e.getMessage(), false);
        tracker.dispatch();
        revenue = 0;
    }
    

Providing the tracker with a user ID lets you connect data collected from multiple devices and multiple browsers for the same user. A user ID is typically a non empty string such as username, email address or UUID that uniquely identifies the user. The User ID must be the same for a given user across all her devices and browsers.

        ((YourApplication) getApplication()).getTracker()
                .setUserId("user@email.com");

If user ID is used, it must be persisted locally by the app and set directly on the tracker each time the app is started.

If no user ID is used, the SDK will generate, manage and persist a random id for you.

The Tracker has a method getDefaultTrackMe modifying the object returned by it will change the default values used on each query. Note though that the Tracker will not overwrite any values you set on your own TrackMe object.

Here is the design document written by Thomas to give a brief overview of the SDK project: https://github.com/piwik/piwik-android-sdk/wiki/Design-document

Piwik SDK should work fine with Android API Version >= 7 (Android 2.1.x)

Optional autoBindActivities method is available on API level >= 14.

Check out the full API documentation.

Following command will clean, build, test, generate documentation, do coverage reports and then create a jar.

$ ./gradlew :piwik-sdk:clean :piwik-sdk:assemble :piwik-sdk:test :piwik-sdk:jacocoTestReport :piwik-sdk:generateReleaseJavadoc :piwik-sdk:coveralls --info :piwik-sdk:makeJar

• Coverage output ./piwik-sdk/build/reports/jacoco/jacocoTestReport/html/index.html
• Tests report ./piwik-sdk/build/test-report/debug/index.html
• Javadoc ./piwik-sdk/build/docs/javadoc/index.html

Browse the code or download apk.

• Fork the project
• Create a feature branch based on the 'dev' branch
• Drink coffee and develop an awesome new feature
• Add tests for your new feature
• Make sure that everything still works by running "./gradlew clean assemble test".
• Commit & push the changes to your repo
• Create a pullrequest from your feature branch against the dev branch of the original repo
• Explain your changes, we can see what changed, but tell us why.
• If your PR passes the travis-ci build and has no merge conflicts, just wait, otherwise fix the code first.

Android SDK for Piwik is released under the BSD-3 Clause license, see LICENSE.