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

To install the library, follow these steps:

  1. Add the JitPack repository to your settings.gradle file:
dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        mavenCentral()
        maven { url 'https://jitpack.io' }
    }
}
dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        mavenCentral()
        maven { url = uri("https://jitpack.io") }
    }
}
  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.3.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.

Updated 2 days ago