Skip to content

Migration

Jump to bottom
darken edited this page Dec 9, 2021 · 9 revisions

Migration

Migration is something that is usually necessary when switching between major versions of the Piwik SDK for Android.

v1.0 to v2.0

Thanks to Patrick Geselbracht for collecting these steps (#161).

Gradle

From compile 'org.piwik.sdk:piwik-sdk:1.0.2' to compile 'org.piwik.sdk:piwik-sdk:2.0.0'.

Classes that moved

TrackHelper

TrackHelper moved from org.piwik.sdk to org.piwik.sdk.extra --- the new fully qualified name therefore becomes org.piwik.sdk.extra.TrackHelper

Methods that changed

Creation of a new tracker

Previously, you could add a new tracker by calling Piwik.newTracker(String piwikUrl, int siteId).

Now, you need to create a new TrackerConfig which you then supply to the method, like so:

Piwik.newTracker(new TrackerConfig("https://piwik.example.com", "4223", "DEFAULT_TRACKER"));

A createDefault(String piwikUrl, int siteId) method is available so that no tracker name has to be supplied. This shortens the previous call to:

Piwik.newTracker(TrackerConfig.createDefault("https://piwik.example.com", "4223"));

See: https://github.com/piwik/piwik-sdk-android/pull/157

CustomVariables

CustomVariables have been deprecated. See https://github.com/piwik/piwik-sdk-android/pull/148#issuecomment-277723478

Dry run (e.g. sandbox builds, debug mode)

Instead of setting a flag on the Piwik instance by calling Piwik.getInstance(this).setDryRun(true)to enable dry run, you now supply your own list data structure to which the tracking calls are saved instead of being sent.

For example, use: piwikTracker.setDryRunTarget(debugBuild ? new ArrayList<Packet>() : null);

See: https://github.com/matomo-org/matomo-sdk-android/blob/532a88ac07ce6f99f558fa70d998f1584ad19749/tracker/src/main/java/org/matomo/sdk/Tracker.java#L528

Opt-out

The method for opting out moved from the Piwik class to the Tracker class.

Therefore, e.g. piwikTracker.getPiwik().setOptOut(true) becomes piwikTracker.setOptOut(true)

v2.0 to v3.0

Gradle

From compile 'org.piwik.sdk:piwik-sdk:2.0.0' to compile 'org.piwik.sdk:piwik-sdk:3.0.0'.

Notes

  • TrackHelper.build() can now throw an exception if you supply bad arguments. Argument checking now happens when calling build() not before. There is now a TrackHelper.safelyWith(...) that silently ignores errors.
  • By default you can assume that a method does not return null unless it is explicitly annotated with @Nullable.
  • If you get weird build errors you might have to add this to your modules build.gradle. Embrace the lambdas it's officially supported since Android Studio 3.0 👍.

v3.0 to v4.0

Notes

  • All instances of Piwik have been renamed to Matomo.
  • The package names have changed from org.piwik.sdk to org.matomo.sdk
  • The SDK no longer enforces how the API url has to look. If you previously passed http://your.server the SDK appended piwik.php, this is no longer the case so you now have to pass the fully qualified URL, e.g. http://your.server/piwik.php.
  • Trackers are now build using TrackerBuilder and passing the Matomo instance.
new TrackerBuilder("http://domain/matomo.php", 1, "Default Tracker).build(getMatomo())

The default tracker is now created with:

TrackerBuilder.createDefault("http://domain/matomo.php",1).build(getMatomo())
Clone this wiki locally