Docs

Getting started

Our Android SDK lets you collect user data from Android mobile apps. It includes over 50 methods for tracking screen views, goals, ecommerce orders, and more. To get started, set up your account in Piwik PRO, install our library, and configure the tracker.

Set up Piwik PRO

Before you install our library for Android, you need to set up Piwik PRO. Here's what you need to do:

  1. Log in to Piwik PRO.
  2. Go to Menu > Administration.
  3. Navigate to Sites & apps.
  4. Click Add a site or app.
  5. Type the app name and address, and click Save.
  6. Set the time zone and currency.
  7. Note the site/app ID. The ID is under the app name. Example: 00000000-0000-0000-0000-000000000000.
  8. Note your tracking endpoint URL - the base URL where the SDK will send collected events. By default this is the same as your Piwik PRO instance address (for example https://example.piwik.pro). If your organization uses a custom tracking endpoint, check with your Piwik PRO administrator.

Install the library

Note: Starting from version 2.4.0, the library is distributed via Maven Central. If you previously installed it via JitPack, see Migrating from JitPack below.

To install the library, follow these steps:

  1. Make sure mavenCentral() is included in your project repositories. Most Android projects already have it:
repositories {
    mavenCentral()
}
repositories {
    mavenCentral()
}
  1. Add the dependency to the application module build.gradle file:
dependencies {
    implementation 'pro.piwik:sdk-framework-android:VERSION'
}
dependencies {
    implementation("pro.piwik:sdk-framework-android:VERSION")
}

Note: Replace VERSION with the latest release name. Example: 2.4.0. (Where to find it?)

Set up the tracker

To set up the Piwik PRO tracker, you can use two methods: (1) create and manage the tracker in the Application class or (2) manage the tracker on your own.

Method #1

We recommend using this method for most cases. It forces the implementation of just one abstract method.

To set up the Piwik PRO tracker, follow these steps:

  1. Extend the PiwikApplication class with your Android application class. Provide your tracking endpoint URL (the base URL where the SDK posts events, for example https://example.piwik.pro/) and the site/app ID (Where to find it?)
class YourApplication : PiwikApplication() {
    override fun onCreateTrackerConfig(): TrackerConfig {
        return TrackerConfig.createDefault("https://example.piwik.pro", "site-id")
    }
}
public class YourApplication extends PiwikApplication {
    @Override
    public TrackerConfig onCreateTrackerConfig() {
        return TrackerConfig.createDefault("https://example.piwik.pro", "site-id");
    }
}
  1. Share the Tracker instance across your app. The Tracker is now thread-safe.
val tracker: Tracker = (application as PiwikApplication).tracker
Tracker tracker = ((PiwikApplication) getApplication()).getTracker();
  1. Done! Now your app can use Piwik PRO SDK.
  2. We recommend using the TrackHelper class to track events. For tracking each event with TrackHelper, you will need to pass the Tracker instance.
val tracker: Tracker = (application as PiwikApplication).tracker
TrackHelper.track().screen("Main screen").with(tracker)
Tracker tracker = ((PiwikApplication) getApplication()).getTracker();
TrackHelper.track().screen("Main screen").with(tracker);

Note: The TrackHelper class provides methods for common tracking actions. You can chain these methods to keep the correct order and structure. IDE autocompletion can help you use the SDK more easily.

Method #2

To set up the Piwik PRO tracker, follow these steps:

  1. Manage the tracker on your own. Provide your tracking endpoint URL (the base URL where the SDK posts events, for example https://example.piwik.pro/) and the site/app ID (Where to find it?).
class YourApplication : Application() {
    val tracker: Tracker by lazy {
        Piwik.getInstance(this).newTracker(
            TrackerConfig("https://example.piwik.pro", "site-id", "Default Tracker")
        )
    }
}
public class YourApplication extends Application {
    private Tracker tracker;
    public synchronized Tracker getTracker() {
        if (tracker == null) tracker = Piwik.getInstance(this).newTracker(new TrackerConfig("https://example.piwik.pro", "site-id", "Default Tracker"));
        return tracker;
    }
}

Note: We recommend using just one tracker instance for your app. Otherwise, you may end up with over-counted metrics.

  1. Share the Tracker instance across your app. The Tracker is now thread-safe.
val tracker: Tracker = (application as YourApplication).tracker
Tracker tracker = ((YourApplication) getApplication()).getTracker();
  1. Done! Now your app can use Piwik PRO SDK.
  2. We recommend using the TrackHelper class to track events. For tracking each event with TrackHelper, you will need to pass the Tracker instance.
val tracker: Tracker = (application as YourApplication).tracker
TrackHelper.track().screen("Main screen").with(tracker)
Tracker tracker = ((YourApplication) getApplication()).getTracker();
TrackHelper.track().screen("Main screen").with(tracker);

Note: The TrackHelper class provides methods for common tracking actions. You can chain these methods to keep the correct order and structure. IDE autocompletion can help you use the SDK more easily.

Migrating from JitPack

Versions 2.4.0 and later are distributed via Maven Central. The dependency coordinates are unchanged, so the implementation line stays the same:

implementation 'pro.piwik:sdk-framework-android:VERSION'
implementation("pro.piwik:sdk-framework-android:VERSION")

Update your project's repositories:

  1. Make sure mavenCentral() is present in the repositories block.
  2. Remove the maven { url 'https://jitpack.io' } entry unless other dependencies still require it.

Versions up to 2.3.0 remain available on JitPack.

Updated 6 days ago