qbisins/piwik-java-tracker

Official Java implementation of the Piwik Tracking HTTP API.

Download

Step 1. Add the JitPack repository to your build file

Add it in your root settings.gradle at the end of repositories:

	dependencyResolutionManagement {
		repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
		repositories {
			mavenCentral()
			maven { url 'https://jitpack.io' }
		}
	}

Add it in your settings.gradle.kts at the end of repositories:

	dependencyResolutionManagement {
		repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
		repositories {
			mavenCentral()
			maven { url = uri("https://jitpack.io") }
		}
	}

Add to pom.xml

	<repositories>
		<repository>
		    <id>jitpack.io</id>
		    <url>https://jitpack.io</url>
		</repository>
	</repositories>

Add it in your build.sbt at the end of resolvers:

 
    resolvers += "jitpack" at "https://jitpack.io"

Add it in your project.clj at the end of repositories:

 
    :repositories [["jitpack" "https://jitpack.io"]]

Step 2. Add the dependency

	dependencies {
		implementation 'com.github.qbisins:piwik-java-tracker:v1.2'
	}
	dependencies {
		implementation("com.github.qbisins:piwik-java-tracker:v1.2")
	}
	<dependency>
	    <groupId>com.github.qbisins</groupId>
	    <artifactId>piwik-java-tracker</artifactId>
	    <version>v1.2</version>
	</dependency>

                            
    libraryDependencies += "com.github.qbisins" % "piwik-java-tracker" % "v1.2"
        
        

                            
    :dependencies [[com.github.qbisins/piwik-java-tracker "v1.2"]]

Readme

Piwik Java Tracker

Maven Central

Code Status

Build Status Coverage Status Average time to resolve an issue Percentage of issues still open

Official Java implementation of the Piwik Tracking HTTP API.

Javadoc

The Javadoc for this project is hosted as a Github page for this repo. The latest Javadoc can be found here. Javadoc for the latest and all releases can be found here.

Using this API

Create a Request

Each PiwikRequest represents an action the user has taken that you want tracked by your Piwik server. Create a PiwikRequest through

PiwikRequest request = new PiwikRequest(siteId, actionUrl);

The following parameters are also enabled by default:

required = true;
visitorId = random 16 character hex string;
randomValue = random 20 character hex string;
apiVersion = 1;
responseAsImage = false;

Overwrite these properties as desired.

Note that if you want to be able to track campaigns using <em>Referrers > Campaigns</em>, you must add the correct URL parameters to your actionUrl. For example,

URL actionUrl = new URL("http://example.org/landing.html?pk_campaign=Email-Nov2011&pk_kwd=LearnMore");

See Tracking Campaigns for more information.

All HTTP query parameters denoted on the Piwik Tracking HTTP API can be set using the appropriate getters and setters. See <strong>PiwikRequest.java</strong> for the mappings of the parameters to their corresponding Java getters/setters.

####Some parameters are dependent on the state of other parameters: <strong>EcommerceEnabled</strong> must be called before the following parameters are set: <em>EcommerceId</em> and <em>EcommerceRevenue</em>.

<strong>EcommerceId</strong> and <strong>EcommerceRevenue</strong> must be set before the following parameters are set: <em>EcommerceDiscount</em>, <em>EcommerceItem</em>, <em>EcommerceLastOrderTimestamp</em>, <em>EcommerceShippingCost</em>, <em>EcommerceSubtotal</em>, and <em>EcommerceTax</em>.

<strong>AuthToken</strong> must be set before the following parameters are set: <em>VisitorCity</em>, <em>VisitorCountry</em>, <em>VisitorIp</em>, <em>VisitorLatitude</em>, <em>VisitorLongitude</em>, and <em>VisitorRegion</em>.

Sending Requests

Create a PiwikTracker through

PiwikTracker tracker = new PiwikTracker(hostUrl);

where hostUrl is the url endpoint of the Piwik server. Usually in the format <strong>http://your-piwik-domain.tld/piwik.php</strong>.

To send a single request, call

HttpResponse response = tracker.sendRequest(request);

If you have multiple requests to wish to track, it may be more efficient to send them in a single HTTP call. To do this, send a bulk request. Place your requests in an <strong>Iterable</strong> data structure and call

HttpResponse response = tracker.sendBulkRequest(requests);

If some of the parameters that you've specified in the bulk request requre AuthToken to be set, this can also be set in the bulk request through

HttpResponse response = tracker.sendBulkRequest(requests, authToken);

Install

This project can be tested and built by calling

mvn package

The built jars and javadoc can be found in <strong>target</strong>

Test this project using

mvn test

This project also supports Pitest mutation testing. This report can be generated by calling

mvn org.pitest:pitest-maven:mutationCoverage

and will produce an html report at <strong>target/pit-reports/YYYYMMDDHHMI</strong>

Clean this project using

mvn clean

Contribute

Have a fantastic feature idea? Spot a bug? We would absolutely love for you to contribute to this project! Please feel free to:

  • Fork this project
  • Create a feature branch from the <strong>dev</strong> branch
  • Write awesome code that does awesome things
  • Write awesome test that test your awesome code
  • Verify that everything is working as it should by running <strong>mvn test</strong>. If everything passes, you may want to make sure that your tests are covering everything you think they are! Run <strong>mvn org.pitest:pitest-maven:mutationCoverage</strong> to find out!
  • Commit this code to your repository
  • Submit a pull request from your branch to our dev branch and let us know why you made the changes you did
  • We'll take a look at your request and work to get it integrated with the repo!

Contact

brett.csorba@gmail.com

License

This software is released under the BSD 3-Clause license. See LICENSE.

Copyright

Copyright (c) 2015 General Electric Company. All rights reserved.