Getting started

Getting started

Setup

Server

• If don't a server running Matomo already, follow these instructions to install Matomo on a server.
• Create a new website (or app) in the Matomo web interface.
• Copy and note the Website ID from "Settings > Websites" and your server address.

Client

Including the library

Add this to your app modules build.gradle file, e.g. ~/git/MyApp/app/build.gradle

dependencies {
    maven { url 'https://jitpack.io' }
    implementation 'com.github.matomo-org:matomo-sdk-android:<latest-version>'
}

Replace <latest-version> with the latest release name, see releases for the latest one.

You can also build the sdk yourself from the source code and include it as jar/aar file. You might consider this if there are changes that have not yet been released.

Client configuration

Basic

You can simply have your application extend our MatomoApplication class. You will be forced to implement a few abstract methods. This approach is used in our demo app.

Advanced

You can also manage the Tracker yourself. To ensure that the metrics are not over-counted, it is highly recommended that the tracker is created and managed in the Application class (i.e. not created twice). The Tracker itself is thread-safe and can be shared through out your application. It's not recommended to create multiple Tracker instances for the same target.

import java.net.MalformedURLException;

public class YourApplication extends Application {
    private Tracker mMatomoTracker;

    public synchronized Tracker getTracker() {
        if (mMatomoTracker != null) return mMatomoTracker;
        mMatomoTracker = TrackerBuilder.createDefault("http://your-matomo-domain.tld/matomo.php", 1).builld(Matomo.getInstance(this));
        return mMatomoTracker;
    }
    //...
}

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

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

Using Matomo

The recommended way to use the library is by using the TrackHelper class. It has methods for all common actions which can be chained in a way that facilities the correct order and use.

Just by using autocompletion on TrackHelper. you can probably get pretty far.

Track screen views

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);
        Tracker tracker = ((MatomoApplication) getApplication()).getTracker();
        TrackHelper.track().screen("/your_activity").title("Title").with(tracker);
    }
}

Track events

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 method.

TrackHelper.track().event("category", "action").name("label").value(1000f).with(tracker);

Track goals

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 Matomo.

TrackHelper.track().goal(1).revenue(revenue).with(tracker)

Track custom values

To track a custom name-value pair assigned to your users or screen views use Custom Dimensions. Note that the custom value data is not send by itself, but only with other tracking actions such as screenviews or events. More about custom variables on matomo.org.

Tracker tracker = ((MatomoApplication) getApplication()).getTracker();
TrackHelper.track().screen("/path").dimension(1, "TestValue").with(tracker);

1 is our dimension slot and TestValue the dimension value.

Track installs

You can also track installs.

TrackHelper.track().download().with(tracker);

Ecommerce

Matomo 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 = ((MatomoApplication) getApplication()).getTracker();
EcommerceItems items = new EcommerceItems();
items.addItem(new EcommerceItems.Item("sku").name("product").category("category").price(200).quantity(2));
items.addItem(new EcommerceItems.Item("sku").name("product2").category("category2").price(400).quantity(3));

TrackHelper.track().order("orderId", 10000).subTotal(7000).tax(2000).shipping(1000).discount(0).items(items).with(tracker);