Skip to content

Commit

Permalink
Update README.md and integrate coverage badge
Browse files Browse the repository at this point in the history
  • Loading branch information
@dheid
dheid committed Nov 3, 2023
1 parent 974053a commit e2fb8d6
Show file tree
Hide file tree
Showing 2 changed files with 48 additions and 75 deletions.
2 changes: 2 additions & 0 deletions .github/workflows/build.yml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -25,3 +25,5 @@ jobs:
token: ${{ secrets.GITHUB_TOKEN }}
min-coverage-overall: 80
min-coverage-changed-files: 80
- uses: cicirello/[email protected]

121 changes: 46 additions & 75 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,8 @@
[![Build Status](https://github.com/matomo-org/matomo-java-tracker/actions/workflows/build.yml/badge.svg)](https://github.com/matomo-org/matomo-java-tracker/actions/workflows/build.yml)
[![Average time to resolve an issue](https://isitmaintained.com/badge/resolution/matomo-org/matomo-java-tracker.svg)](https://isitmaintained.com/project/matomo-org/matomo-java-tracker "Average time to resolve an issue")
[![Percentage of issues still open](https://isitmaintained.com/badge/open/matomo-org/matomo-java-tracker.svg)](https://isitmaintained.com/project/matomo-org/matomo-java-tracker "Percentage of issues still open")
![Line Coverage](.github/badges/jacoco.svg)
![Branch Coverage](.github/badges/branches.svg)

Matomo Java Tracker is the official Java implementation of
the [Matomo Tracking HTTP API](https://developer.matomo.org/api-reference/tracking-api). The tracker allows you to track
Expand All @@ -25,6 +27,15 @@ Features include:
* Includes debug and error logging
* Easy to integrate in frameworks, e.g. Spring: Just create the MatomoTracker Spring bean and use it in other beans

Further information on Matomo and Matomo HTTP tracking:

* [Matomo PHP Tracker](https://github.com/matomo-org/matomo-php-tracker)
* [Matomo Tracking HTTP API](https://developer.matomo.org/api-reference/tracking-api)
* [Introducting the Matomo Java Tracker](https://matomo.org/blog/2015/11/introducing-piwik-java-tracker/)
* [Tracking API User Guide](https://matomo.org/guide/apis/tracking-api/)
* [Matomo Developer](https://developer.matomo.org/)
* [The Matomo project](https://matomo.org/)

## Table of Contents

* [What Is New?](#what-is-new)
Expand All @@ -35,7 +46,6 @@ Features include:
* [Building](#building)
* [Versioning](#versioning)
* [Contribute](#contribute)
* [Further information](#further-information)
* [License](#license)

## What Is New?
Expand All @@ -48,43 +58,21 @@ Here are the most important changes:
* Matomo Java Tracker 3.x is compatible with Matomo 4 and 5
* less dependencies
* new dimension parameter
* new visitor id parameter
* new random value parameter
* new device resolution parameter
* new locale parameter
* new country parameter
* new page view id parameter
* special types allow to provide valid parameters now

## Javadoc

The Javadoc for this project is hosted as a GitHub page for this repo. The latest Javadoc can be
found [here](https://matomo-org.github.io/matomo-java-tracker/javadoc/index.html).

Javadoc folder older versions can be found here: https://javadoc.io/doc/org.piwik.java.tracking/matomo-java-tracker

You can also build the Javadoc yourself. See the section _Building_ below.
found [here](https://matomo-org.github.io/matomo-java-tracker/javadoc/index.html). Javadoc folder older versions can be found here: https://javadoc.io/doc/org.piwik.java.tracking/matomo-java-tracker
You can also build the Javadoc yourself. See the section [Building](#building) below.

## Need help?

* Open an issue in this repository: https://github.com/matomo-org/matomo-java-tracker/issues
* Use discussions: https://github.com/matomo-org/matomo-java-tracker/discussions
* Ask your question on Stackoverflow with the tag `matomo`: https://stackoverflow.com/questions/tagged/matomo
* Use other communication channels:
* Matomo forum: https://forum.matomo.org/
* Matomo Slack: https://matomo.org/slack/
* Matomo Telegram: https://t.me/matomo_analytics
* Matomo Discord: https://discord.gg/7M2gtrT
* Matomo Matrix: https://matrix.to/#/#matomo:matrix.org
* Matomo IRC: https://web.libera.chat/#matomo
* Matomo Twitter: https://twitter.com/matomo
* Matomo LinkedIn: https://www.linkedin.com/company/matomo-analytics
* Matomo Facebook: https://www.facebook.com/matomo.org
* Matomo Instagram: https://www.instagram.com/matomo_org/
* Matomo YouTube: https://www.youtube.com/user/MatomoAnalytics
* Matomo Reddit: https://www.reddit.com/r/matomo/
* Matomo Pinterest: https://www.pinterest.com/matomoorg/
* Matomo Mastodon: https://fosstodon.org/@matomo
* Open an issue in the (Issue Tracker)[https://github.com/matomo-org/matomo-java-tracker/issues]
* Use [our GitHub discussions](https://github.com/matomo-org/matomo-java-tracker/discussions)
* Ask your question on (Stackoverflow with the tag `matomo`)[https://stackoverflow.com/questions/tagged/matomo]
* Create a thread in the [Matomo Forum](https://forum.matomo.org/)
* Contact [Matomo Support](https://matomo.org/support/)

## Using this API

Expand Down Expand Up @@ -178,11 +166,10 @@ public class YourImplementation {
}
```

See [Tracking Campaigns](https://matomo.org/docs/tracking-campaigns/) for more information.

All HTTP query parameters denoted on
See [Tracking Campaigns](https://matomo.org/docs/tracking-campaigns/) for more information. All HTTP query parameters denoted on
the [Matomo Tracking HTTP API](https://developer.matomo.org/api-reference/tracking-api) can be set using the appropriate
getters and setters. See _MatomoRequest.java_ for the mappings of the parameters to their corresponding attributes.
getters and setters. See [MatomoRequest.java](src/main/java/org/matomo/api/MatomoRequest.java) for the mappings of the
parameters to their corresponding attributes.

Requests are validated prior to sending. If a request is invalid, a `MatomoException` will be thrown.

Expand Down Expand Up @@ -232,7 +219,7 @@ The Matomo Tracker currently supports the following builder methods:
* `.proxyPassword(...)` The corresponding password for the basic auth proxy user. The proxy host,
port and user name must be set as well.

To send a single request, call
To send a single request synchronously via GET, call

```java
package example;
Expand Down Expand Up @@ -363,9 +350,9 @@ following breaking changes:

* The parameter `actionTime` (`gt_ms`) is no longer supported by Matomo 5 and was removed.
* Many methods marked as deprecated in version 2 were removed. Please see the
former [Javadoc](https://matomo-org.github.io/matomo-java-tracker/javadoc/HEAD/index.html) of version 2 to get the
former [Javadoc](https://javadoc.io/doc/org.piwik.java.tracking/matomo-java-tracker/2.1/index.html) of version 2 to get the
deprecated methods.
* We removed the vulnerable dependency to the Apache HTTP client. Callbacks are no longer of type `FutureCallback`, but
* We removed the vulnerable dependency to the Apache HTTP client. Callbacks are no longer of type `FutureCallback<HttpResponse>`, but
`Consumer<Void>` instead.
* The `send...` methods of `MatomoTracker` no longer return a value (usually Matomo always returns an HTTP 204 response
without a body). If the request fails, an exception will be thrown.
Expand All @@ -379,84 +366,76 @@ following breaking changes:
will be validated prior to sending and not during construction.
* `getRandomHexString` was removed. Use `RandomValue.random()` or `VisitorId.random()` instead.

## Type Changes and Renaming
### Type Changes and Renaming

* `requestDatetime`, `visitorPreviousVisitTimestamp`, `visitorFirstVisitTimestamp`, `ecommerceLastOrderTimestamp` are
now of type `Instant`. You can use `Instant.ofEpochSecond()` to create
of type `Instant`. You can use `Instant.ofEpochSecond()` to create
them from epoch seconds.
* `requestDatetime` was renamed to `requestTimestamp` due to setter collision and downwards compatibility
* `goalRevenue` is the same parameter as `ecommerceRevenue` and was removed to prevent duplication.
Use `ecommerceRevenue` instead.
* `setEventValue` requires a double parameter now
* `setEcommerceLastOrderTimestamp` requires an `Instant` parameter now
* `headerAcceptLanguage` is now of type `AcceptLanguage`. You can build it easily
* `setEventValue` requires a double parameter
* `setEcommerceLastOrderTimestamp` requires an `Instant` parameter
* `headerAcceptLanguage` is of type `AcceptLanguage`. You can build it easily
using `AcceptLanguage.fromHeader("de")`
* `visitorCountry` is now of type `Country`. You can build it easily using `AcceptLanguage.fromCode("fr")`
* `deviceResolution` is now of type `DeviceResolution`. You can build it easily
* `visitorCountry` is of type `Country`. You can build it easily using `AcceptLanguage.fromCode("fr")`
* `deviceResolution` is of type `DeviceResolution`. You can build it easily
using `DeviceResolution.builder.width(...).height(...).build()`. To easy the migration, we added a constructor
method `DeviceResolution.fromString()` that accepts inputs of kind _width_x_height_, e.g. `100x200`
* `pageViewId` is now of type `UniqueId`. You can build it easily using `UniqueId.random()`
* `randomValue` is now of type `RandomValue`. You can build it easily using `RandomValue.random()`. However, if you
* `pageViewId` is of type `UniqueId`. You can build it easily using `UniqueId.random()`
* `randomValue` is of type `RandomValue`. You can build it easily using `RandomValue.random()`. However, if you
really
want to insert a custom string here, use `RandomValue.fromString()` construction method.
* URL was removed due to performance and complicated exception handling and problems with parsing of complex
URLs. `actionUrl`, `referrerUrl`, `outlinkUrl`, `contentTarget` and `downloadUrl` are now strings.
* `getCustomTrackingParameter()` of `MatomoRequest` returns an unmodifiable list now.
URLs. `actionUrl`, `referrerUrl`, `outlinkUrl`, `contentTarget` and `downloadUrl` are strings.
* `getCustomTrackingParameter()` of `MatomoRequest` returns an unmodifiable list.
* Instead of `IllegalStateException` the tracker throws `MatomoException`
* In former versions the goal id had always to be zero or null. You can now define higher numbers than zero.
* In former versions the goal id had always to be zero or null. You can define higher numbers than zero.
* For more type changes see the sections below.

### Visitor ID

* `visitorId` and `visitorCustomId` are now of type `VisitorId`. You can build them easily
* `visitorId` and `visitorCustomId` are of type `VisitorId`. You can build them easily
using `VisitorId.fromHash(...)`.
* You can use `VisitorId.fromHex()` to create a `VisitorId` from a string that contains only hexadecimal characters.
* VisitorId.fromHex() now supports less than 16 hexadecimal characters. If the string is shorter than 16 characters,
* VisitorId.fromHex() supports less than 16 hexadecimal characters. If the string is shorter than 16 characters,
the remaining characters will be filled with zeros.

### Custom Variables

* According to Matomo, custom variables should no longer be used. Please use dimensions instead. Dimension support has
been introduced.
* `CustomVariable` is now in package `org.matomo.java.tracking.parameters`.
* `CustomVariable` is in package `org.matomo.java.tracking.parameters`.
* `customTrackingParameters` in `MatomoRequestBuilder` requires a `Map<String, Collection<String>>` instead
of `Map<String, String>` now
* `pageCustomVariables` and `visitCustomVariables` are now of type `CustomVariables` instead of collections. Create them
of `Map<String, String>`
* `pageCustomVariables` and `visitCustomVariables` are of type `CustomVariables` instead of collections. Create them
with `CustomVariables.builder().variable(customVariable)`
* `setPageCustomVariable` and `getPageCustomVariable` now longer accept a string as an index. Please use integers
* `setPageCustomVariable` and `getPageCustomVariable` no longer accept a string as an index. Please use integers
instead.
* Custom variables will now be sent URL encoded
* Custom variables will be sent URL encoded

## Building
## Building and testing

This project can be tested and built by calling

```shell
mvn install
```

The built jars and javadoc can be found in `target`. By using the Maven goal `install, the snapshot
The built jars and javadoc can be found in `target`. By using the Maven goal `install, a snapshot
version can be used in your local Maven repository for testing purposes, e.g.

```xml

<dependency>
<groupId>org.piwik.java.tracking</groupId>
<artifactId>matomo-java-tracker</artifactId>
<version>3.0.0-rc2-SNAPSHOT</version>
</dependency>
```

Clean this project using

```shell
mvn clean
```

## Versioning

We use [SemVer](http://semver.org/) for versioning. For the versions available, see
the [tags on this repository](https://github.com/matomo-org/matomo-java-tracker/tags).
We use [SemVer](http://semver.org/) for versioning. For the versions available, see the [tags on this repository](https://github.com/matomo-org/matomo-java-tracker/tags).

## Contribute

Expand All @@ -480,14 +459,6 @@ process for submitting pull requests to us.
We use Checkstyle and JaCoCo to ensure code quality. Please run `mvn verify` before submitting a pull request. Please
provide tests for your changes. We use JUnit 5 for testing. Coverage should be at least 80%.

## Further information

* [Matomo PHP Tracker](https://github.com/matomo-org/matomo-php-tracker)
* [Matomo Tracking HTTP API](https://developer.matomo.org/api-reference/tracking-api)
* [Introducting the Matomo Java Tracker](https://matomo.org/blog/2015/11/introducing-piwik-java-tracker/)
* [Tracking API User Guide](https://matomo.org/guide/apis/tracking-api/)
* [Matomo](https://matomo.org/) - The Matomo project

## License

This software is released under the BSD 3-Clause license. See [LICENSE](LICENSE).
Expand Down

0 comments on commit e2fb8d6

Please sign in to comment.