{"id":28398990,"url":"https://github.com/matomo-org/matomo-java-tracker","last_synced_at":"2025-06-28T18:30:43.681Z","repository":{"id":35317685,"uuid":"39579298","full_name":"matomo-org/matomo-java-tracker","owner":"matomo-org","description":"Official Java implementation of the Matomo Tracking HTTP API.","archived":false,"fork":false,"pushed_at":"2025-05-05T21:52:10.000Z","size":12299,"stargazers_count":75,"open_issues_count":9,"forks_count":53,"subscribers_count":20,"default_branch":"main","last_synced_at":"2025-06-19T15:26:59.217Z","etag":null,"topics":["analytics","android","dsl","java","java-client","java-client-sdk","kotlin","matomo","matomo-analytics","matomo-sdk","matomo-tracking","matomo-web-analytics","metrics","mobile","piwik","piwik-sdk","tracker","web-analytics"],"latest_commit_sha":null,"homepage":"https://matomo-org.github.io/matomo-java-tracker/","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/matomo-org.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2015-07-23T16:45:28.000Z","updated_at":"2025-06-16T08:15:04.000Z","dependencies_parsed_at":"2023-12-08T07:04:13.047Z","dependency_job_id":"6258e9ec-4c79-4b40-a661-1aa40526a298","html_url":"https://github.com/matomo-org/matomo-java-tracker","commit_stats":{"total_commits":399,"total_committers":20,"mean_commits":19.95,"dds":0.6340852130325815,"last_synced_commit":"528edb0903a313baf3e8f8c2b4970a56cc7762e8"},"previous_names":["piwik/piwik-java-tracker"],"tags_count":39,"template":false,"template_full_name":null,"purl":"pkg:github/matomo-org/matomo-java-tracker","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/matomo-org%2Fmatomo-java-tracker","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/matomo-org%2Fmatomo-java-tracker/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/matomo-org%2Fmatomo-java-tracker/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/matomo-org%2Fmatomo-java-tracker/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/matomo-org","download_url":"https://codeload.github.com/matomo-org/matomo-java-tracker/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/matomo-org%2Fmatomo-java-tracker/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":260993706,"owners_count":23094268,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["analytics","android","dsl","java","java-client","java-client-sdk","kotlin","matomo","matomo-analytics","matomo-sdk","matomo-tracking","matomo-web-analytics","metrics","mobile","piwik","piwik-sdk","tracker","web-analytics"],"created_at":"2025-06-01T06:38:43.798Z","updated_at":"2025-06-28T18:30:43.668Z","avatar_url":"https://github.com/matomo-org.png","language":"Java","readme":"# Official Matomo Java Tracker\n\n[![Maven Central](https://maven-badges.herokuapp.com/maven-central/org.piwik.java.tracking/matomo-java-tracker/badge.svg?style=flat)](https://maven-badges.herokuapp.com/maven-central/org.piwik.java.tracking/matomo-java-tracker)\n[![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)\n[![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\")\n[![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\")\n\nThe Matomo Java Tracker functions as the official Java implementation for\nthe [Matomo Tracking HTTP API](https://developer.matomo.org/api-reference/tracking-api). This versatile tracker empowers\nyou to monitor visits, goals, and ecommerce transactions and items. Specifically designed for integration into\nserver-side applications, it seamlessly integrates with Java-based web applications or web services.\n\nKey features:\n\n* Comprehensive tracking capabilities: Monitor page views, goals, ecommerce transactions, and items.\n* Customization options: Support for custom dimensions and variables.\n* Extensive tracking parameters: Capture data on campaigns, events, downloads, outlinks, site searches, devices, and\n  visitors.\n* Java compatibility: Supports Java 8 and higher, with a dedicated artifact (matomo-java-tracker-java11) for Java 11.\n* SSL certificate flexibility: Option to skip SSL certificate validation (caution: not recommended for production).\n* Minimal runtime dependencies: Relies solely on SLF4J.\n* Asynchronous request support: Permits non-blocking requests.\n* Compatibility with Matomo versions 4 and 5.\n* Versatile request handling: Send both single and multiple requests.\n* Robust documentation: Thoroughly documented with Javadoc for easy reference.\n* Data accuracy assurance: Ensures correct values are transmitted to the Matomo Tracking API.\n* Logging capabilities: Include debug and error logging for effective troubleshooting.\n* Seamless integration: Easily integrates into frameworks such as Spring by creating the MatomoTracker Spring bean for\n  use in other beans.\n\nPlease prefer the Java 11 version as the Java 8 will become obsolete in the future.\n\nYou can find our [Developer Guide here](https://developer.matomo.org/api-reference/tracking-java)\n\nFurther information on Matomo and Matomo HTTP tracking:\n\n* [Matomo PHP Tracker](https://github.com/matomo-org/matomo-php-tracker)\n* [Matomo Tracking HTTP API](https://developer.matomo.org/api-reference/tracking-api)\n* [Introducing the Matomo Java Tracker](https://matomo.org/blog/2015/11/introducing-piwik-java-tracker/)\n* [Tracking API User Guide](https://matomo.org/guide/apis/tracking-api/)\n* [Matomo Developer](https://developer.matomo.org/)\n* [The Matomo project](https://matomo.org/)\n\nProjects that use Matomo Java Tracker:\n\n* [Box-c - supports the UNC Libraries' Digital Collections Repository](https://github.com/UNC-Libraries/box-c)\n* [DSpace - provide durable access to digital resources](https://github.com/thanvanlong/dspace)\n* [Identifiers.org satellite Web SPA](https://github.com/identifiers-org/cloud-satellite-web-spa)\n* [Cloud native Resolver Web Service for identifiers.org](https://github.com/identifiers-org/cloud-ws-resolver)\n* [Resource Catalogue](https://github.com/madgeek-arc/resource-catalogue)\n* [INCEpTION - A semantic annotation platform offering intelligent assistance and knowledge management](https://github.com/inception-project/inception)\n* [QualiChain Analytics Intelligent Profiling](https://github.com/JoaoCabrita95/IP)\n* [Digitale Ehrenamtskarte](https://github.com/digitalfabrik/entitlementcard)\n* [skidfuscator-java-obfuscator](https://github.com/skidfuscatordev/skidfuscator-java-obfuscator)\n* [DnA](https://github.com/mercedes-benz/DnA)\n* And many closed source projects that we are not aware of :smile:\n\n## Table of Contents\n\n* [What Is New?](#what-is-new)\n* [Javadoc](#javadoc)\n* [Need help?](#need-help)\n* [Using this API](#using-this-api)\n* [Migration from Version 2 to 3](#migration-from-version-2-to-3)\n* [Building and Testing](#building-and-testing)\n* [Versioning](#versioning)\n* [Contribute](#contribute)\n* [License](#license)\n\n## What Is New?\n\n### Version 3.4.x\n\nWe fixed a synchronization issue in the Java 8 sender (https://github.com/matomo-org/matomo-java-tracker/issues/168). \nTo consume the exact amount of space needed for the queries to send to Matomo, we need the collection size of the incoming\nrequests. So we changed `Iterable` to `Collection` in some `MatomoTracker`. This could affect users, that use parameters\nof type `Iterable` in the tracker. Please use `Collection` instead.\n\n### Version 3.3.x\n\nDo you still use Matomo Java Tracker 2.x? We created version 3, that is compatible with Matomo 4 and 5 and contains\nfewer\ndependencies. Release notes can be found here: https://github.com/matomo-org/matomo-java-tracker/releases\n\nHere are the most important changes:\n\n* Matomo Java Tracker 3.4.0 is compatible with Matomo 4 and 5\n* less dependencies\n* new dimension parameter\n* special types allow to provide valid parameters now\n* a new implementation for Java 11 uses the HttpClient available since Java 11\n\nSee also the [Developer Guide here](https://developer.matomo.org/api-reference/tracking-java)\n\n## Javadoc\n\nThe Javadoc for all versions can be found\n[at javadoc.io](https://javadoc.io/doc/org.piwik.java.tracking/matomo-java-tracker-core/latest/index.html). Thanks to\n[javadoc.io](https://javadoc.io) for hosting it.\n\n## Need help?\n\n* Check the [Developer Guide](https://developer.matomo.org/api-reference/tracking-java)\n* Open an issue in the [Issue Tracker](https://github.com/matomo-org/matomo-java-tracker/issues)\n* Use [our GitHub discussions](https://github.com/matomo-org/matomo-java-tracker/discussions)\n* Ask your question on [Stackoverflow with the tag `matomo`](https://stackoverflow.com/questions/tagged/matomo)\n* Create a thread in the [Matomo Forum](https://forum.matomo.org/)\n* Contact [Matomo Support](https://matomo.org/support/)\n\n## Using this API\n\nSee the following sections for information on how to use this API. For more information, see the Javadoc. We also\nrecommend to read the [Tracking API User Guide](https://matomo.org/guide/apis/tracking-api/).\nThe [Matomo Tracking HTTP API](https://developer.matomo.org/api-reference/tracking-api) is well\ndocumented and contains many examples.\n\nThis project contains the following Maven artifacts:\n\n1. **matomo-java-tracker-core**: This artifact is the core module of the Matomo Java Tracker project. It provides the\n   main functionality of the Matomo Java Tracker, which is a Java implementation for the Matomo Tracking HTTP API. This\n   module is designed to be used as a base for other modules in the project that provide additional functionality or\n   integrations.\n2. **matomo-java-tracker**: This is a specific implementation of the core module designed for Java 8. It provides the\n   main functionality of the Matomo Java Tracker and is built upon the core. This artifact is\n   specifically designed for applications running on Java 8.\n3. **matomo-java-tracker-java11**: This artifact is a Java 11 implementation of the Matomo Java Tracker. It uses the\n   HttpClient available since Java 11. It is recommended to use this version if you are using Java 11 or higher.\n4. **matomo-java-tracker-spring-boot-starter**: This artifact is a Spring Boot Starter for the Matomo Java Tracker. It\n   provides auto-configuration for the Matomo Java Tracker in a Spring Boot application. By including this artifact in\n   your project, you can take advantage of Spring Boot's auto-configuration features to automatically set up and\n   configure the Matomo Java Tracker.\n5. **matomo-java-tracker-servlet-jakarta**: This artifact is specifically designed for applications using the Jakarta\n   Servlet API (part of Jakarta EE).\n6. **matomo-java-tracker-servlet-javax**: This artifact is specifically designed for applications using the older Java\n   Servlet API (part of Java EE).\n7. **matomo-java-tracker-test**: This artifact contains tools for manual testing against a local Matomo instance created\n   with Docker. It contains a tester class that sends randomized requests to a local Matomo instance and a servlet that\n   can be used to test the servlet integration.\n\nEach of these artifacts serves a different purpose and can be used depending on the specific needs of your project and\nthe Java version you are using.\n\n### Add library to your build\n\nAdd a dependency on Matomo Java Tracker using Maven. For Java 8:\n\n```xml\n\n\u003cdependency\u003e\n    \u003cgroupId\u003eorg.piwik.java.tracking\u003c/groupId\u003e\n    \u003cartifactId\u003ematomo-java-tracker\u003c/artifactId\u003e\n    \u003cversion\u003e3.4.0\u003c/version\u003e\n\u003c/dependency\u003e\n```\n\nFor Java 11:\n\n```xml\n\n\u003cdependency\u003e\n    \u003cgroupId\u003eorg.piwik.java.tracking\u003c/groupId\u003e\n    \u003cartifactId\u003ematomo-java-tracker-java11\u003c/artifactId\u003e\n    \u003cversion\u003e3.4.0\u003c/version\u003e\n\u003c/dependency\u003e\n```\n\nor Gradle (Java 8):\n\n```groovy\ndependencies {\n    implementation(\"org.piwik.java.tracking:matomo-java-tracker:3.4.0\")\n}\n```\n\nor Gradle (Java 11):\n\n```groovy\ndependencies {\n    implementation(\"org.piwik.java.tracking:matomo-java-tracker-java11:3.4.0\")\n}\n```\n\nor Gradle with Kotlin DSL (Java 8)\n\n```kotlin\nimplementation(\"org.piwik.java.tracking:matomo-java-tracker:3.4.0\")\n```\n\nor Gradle with Kotlin DSL (Java 11)\n\n```kotlin\nimplementation(\"org.piwik.java.tracking:matomo-java-tracker-java11:3.4.0\")\n```\n\n### Spring Boot Module\n\nIf you use Spring Boot 3, you can use the Spring Boot Starter artifact. It will create a MatomoTracker bean for you\nand allows you to configure the tracker via application properties. Add the following dependency to your build:\n\n```xml\n\n\u003cdependency\u003e\n    \u003cgroupId\u003eorg.piwik.java.tracking\u003c/groupId\u003e\n    \u003cartifactId\u003ematomo-java-tracker-spring-boot-starter\u003c/artifactId\u003e\n    \u003cversion\u003e3.4.0\u003c/version\u003e\n\u003c/dependency\u003e\n```\n\nor Gradle:\n\n```groovy\ndependencies {\n    implementation(\"org.piwik.java.tracking:matomo-java-tracker-spring-boot-starter:3.4.0\")\n}\n```\n\nor Gradle with Kotlin DSL\n\n```kotlin\nimplementation(\"org.piwik.java.tracking:matomo-java-tracker-spring-boot-starter:3.4.0\")\n```\n\nThe following properties are supported:\n\n| Property Name                                | Description                                                                                                                                            |\n|----------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------|\n| matomo.tracker.api-endpoint (required)       | The URL to the Matomo Tracking API endpoint. Must be set.                                                                                              |\n| matomo.tracker.default-site-id               | If you provide a default site id, it will be taken if the action does not contain a site id.                                                           |\n| matomo.tracker.default-token-auth            | If you provide a default token auth, it will be taken if the action does not contain a token auth.                                                     |\n| matomo.tracker.enabled                       | The tracker is enabled per default. You can disable it per configuration with this flag.                                                               |\n| matomo.tracker.log-failed-tracking           | Will send errors to the log if the Matomo Tracking API responds with an erroneous HTTP code                                                            |\n| matomo.tracker.connect-timeout               | allows you to change the default connection timeout of 10 seconds. 0 is interpreted as infinite, null uses the system default                          |\n| matomo.tracker.socket-timeout                | allows you to change the default socket timeout of 10 seconds. 0 is interpreted as infinite, null uses the system default                              |\n| matomo.tracker.user-agent                    | used by the request made to the endpoint is `MatomoJavaClient` per default. You can change it by using this builder method.                            |\n| matomo.tracker.proxy-host                    | The hostname or IP address of an optional HTTP proxy. `proxyPort` must be configured as well                                                           |\n| matomo.tracker.proxy-port                    | The port of an HTTP proxy. `proxyHost` must be configured as well.                                                                                     |\n| matomo.tracker.proxy-username                | If the HTTP proxy requires a username for basic authentication, it can be configured with this method. Proxy host, port and password must also be set. |\n| matomo.tracker.proxy-password                | The corresponding password for the basic auth proxy user. The proxy host, port and username must be set as well.                                       |\n| matomo.tracker.disable-ssl-cert-validation   | If set to true, the SSL certificate of the Matomo server will not be validated. This should only be used for testing purposes. Default: false          |\n| matomo.tracker.disable-ssl-host-verification | If set to true, the SSL host of the Matomo server will not be validated. This should only be used for testing purposes. Default: false                 |\n| matomo.tracker.thread-pool-size              | The number of threads that will be used to asynchronously send requests. Default: 2                                                                    |\n| matomo.tracker.filter.enabled                | Enables a servlet filter that tracks every request within the application                                                                              |\n\nTo ensure the `MatomoTracker` bean is created by the auto configuration, you have to add the following property to\nyour `application.properties` file:\n\n```properties\nmatomo.tracker.api-endpoint=https://your-matomo-domain.tld/matomo.php\n```\n\nOr if you use YAML:\n\n```yaml\nmatomo:\n    tracker:\n        api-endpoint: https://your-matomo-domain.tld/matomo.php\n```\n\nYou can automatically add the `MatomoTrackerFilter` to your Spring Boot application if you add the following property:\n\n```properties\nmatomo.tracker.filter.enabled=true\n```\n\nOr if you use YAML:\n\n```yaml\nmatomo:\n    tracker:\n        filter:\n            enabled: true\n```\n\nThe filter uses `ServletMatomoRequest` to create a `MatomoRequest` from a `HttpServletRequest` on every filter call.\n\n### Sending a Tracking Request\n\nTo let the Matomo Java Tracker send a request to the Matomo instance, you need the following minimal code:\n\n```java\nimport java.net.URI;\nimport org.matomo.java.tracking.MatomoRequests;\nimport org.matomo.java.tracking.MatomoTracker;\nimport org.matomo.java.tracking.TrackerConfiguration;\nimport org.matomo.java.tracking.parameters.VisitorId;\n\n/**\n * Example for sending a request.\n */\npublic class SendExample {\n\n    /**\n     * Example for sending a request.\n     *\n     * @param args ignored\n     */\n    public static void main(String[] args) {\n\n        TrackerConfiguration configuration = TrackerConfiguration\n                .builder()\n                .apiEndpoint(URI.create(\"https://www.yourdomain.com/matomo.php\"))\n                .defaultSiteId(1)\n                .defaultAuthToken(\"ee6e3dd9ed1b61f5328cf5978b5a8c71\")\n                .logFailedTracking(true)\n                .build();\n\n        try (MatomoTracker tracker = new MatomoTracker(configuration)) {\n            tracker.sendRequestAsync(MatomoRequests\n                    .event(\"Training\", \"Workout completed\", \"Bench press\", 60.0)\n                    .visitorId(VisitorId.fromString(\"customer@mail.com\"))\n                    .build()\n            );\n        } catch (Exception e) {\n            throw new RuntimeException(\"Could not close tracker\", e);\n        }\n    }\n\n}\n\n```\n\nThis will send a request to the Matomo instance at https://www.yourdomain.com/matomo.php and track a page view for the\nvisitor customer@mail.com with the action name \"Checkout\" and action URL \"https://www.yourdomain.com/checkout\" for\nthe site with id 1. The request will be sent asynchronously, that means the method will return immediately and your\napplication will not wait for the response of the Matomo server. In the configuration we set the default site id to 1\nand configure the default auth token. With `logFailedTracking` we enable logging of failed tracking requests.\n\nIf you want to perform an operation after a successful asynchronous call to Matomo, you can use the completable future\nresult like this:\n\n```java\nimport java.net.URI;\nimport org.matomo.java.tracking.MatomoRequest;\nimport org.matomo.java.tracking.MatomoRequests;\nimport org.matomo.java.tracking.MatomoTracker;\nimport org.matomo.java.tracking.TrackerConfiguration;\nimport org.matomo.java.tracking.parameters.VisitorId;\n\n/**\n * Example for sending a request and performing an action when the request was sent successfully.\n */\npublic class ConsumerExample {\n\n    /**\n     * Example for sending a request and performing an action when the request was sent successfully.\n     *\n     * @param args ignored\n     */\n    public static void main(String[] args) {\n\n        TrackerConfiguration configuration = TrackerConfiguration\n                .builder()\n                .apiEndpoint(URI.create(\"https://www.yourdomain.com/matomo.php\"))\n                .defaultSiteId(1)\n                .defaultAuthToken(\"ee6e3dd9ed1b61f5328cf5978b5a8c71\")\n                .logFailedTracking(true)\n                .build();\n\n        try (MatomoTracker tracker = new MatomoTracker(configuration)) {\n            MatomoRequest request = MatomoRequests\n                    .event(\"Training\", \"Workout completed\", \"Bench press\", 60.0)\n                    .visitorId(VisitorId.fromString(\"customer@mail.com\"))\n                    .build();\n\n            tracker.sendRequestAsync(request)\n                    .thenAccept(req -\u003e System.out.printf(\"Sent request %s%n\", req))\n                    .exceptionally(throwable -\u003e {\n                        System.err.printf(\"Failed to send request: %s%n\", throwable.getMessage());\n                        return null;\n                    });\n        } catch (Exception e) {\n            throw new RuntimeException(\"Could not close tracker\", e);\n        }\n\n    }\n\n}\n\n\n```\n\nIf you have multiple requests to wish to track, it may be more efficient to send them in a single HTTP call. To do this,\nsend a bulk request. Place your requests in an _Iterable_ data structure and call\n\n```java\nimport java.net.URI;\nimport org.matomo.java.tracking.MatomoRequests;\nimport org.matomo.java.tracking.MatomoTracker;\nimport org.matomo.java.tracking.TrackerConfiguration;\nimport org.matomo.java.tracking.parameters.VisitorId;\n\n/**\n * Example for sending multiple requests in one bulk request.\n */\npublic class BulkExample {\n\n    /**\n     * Example for sending multiple requests in one bulk request.\n     *\n     * @param args ignored\n     */\n    public static void main(String[] args) {\n\n        TrackerConfiguration configuration = TrackerConfiguration\n                .builder()\n                .apiEndpoint(URI.create(\"https://www.yourdomain.com/matomo.php\"))\n                .defaultSiteId(1)\n                .defaultAuthToken(\"ee6e3dd9ed1b61f5328cf5978b5a8c71\")\n                .logFailedTracking(true)\n                .build();\n\n        try (MatomoTracker tracker = new MatomoTracker(configuration)) {\n            VisitorId visitorId = VisitorId.fromString(\"customer@mail.com\");\n            tracker.sendBulkRequestAsync(\n                    MatomoRequests.siteSearch(\"Running shoes\", \"Running\", 120L)\n                            .visitorId(visitorId).build(),\n                    MatomoRequests.pageView(\"VelocityStride ProX Running Shoes\")\n                            .visitorId(visitorId).build(),\n                    MatomoRequests.ecommerceOrder(\"QXZ-789LMP\", 100.0, 124.0, 19.0, 10.0, 5.0)\n                            .visitorId(visitorId)\n                            .build()\n            );\n        } catch (Exception e) {\n            throw new RuntimeException(\"Could not close tracker\", e);\n        }\n\n    }\n\n}\n```\n\nThis will send two requests in a single HTTP call. The requests will be sent asynchronously.\n\nPer default every request has the following default parameters:\n\n| Parameter Name  | Default Value                  |\n|-----------------|--------------------------------|\n| required        | true                           |\n| visitorId       | random 16 character hex string |\n| randomValue     | random 20 character hex string |\n| apiVersion      | 1                              |\n| responseAsImage | false                          |\n\nOverwrite these properties as desired. We strongly recommend your to determine the visitor id for every user using\na unique identifier, e.g. an email address. If you do not provide a visitor id, a random visitor id will be generated.\n\nEcommerce requests contain ecommerce items, that can be fluently build:\n\n```java\nimport java.net.URI;\nimport org.matomo.java.tracking.MatomoRequests;\nimport org.matomo.java.tracking.MatomoTracker;\nimport org.matomo.java.tracking.TrackerConfiguration;\nimport org.matomo.java.tracking.parameters.EcommerceItem;\nimport org.matomo.java.tracking.parameters.EcommerceItems;\nimport org.matomo.java.tracking.parameters.VisitorId;\n\n/**\n * Example for sending an ecommerce request.\n */\npublic class EcommerceExample {\n\n    /**\n     * Example for sending an ecommerce request.\n     *\n     * @param args ignored\n     */\n    public static void main(String[] args) {\n\n        TrackerConfiguration configuration = TrackerConfiguration\n                .builder()\n                .apiEndpoint(URI.create(\"https://www.yourdomain.com/matomo.php\"))\n                .defaultSiteId(1)\n                .defaultAuthToken(\"ee6e3dd9ed1b61f5328cf5978b5a8c71\")\n                .logFailedTracking(true)\n                .build();\n\n        try (MatomoTracker tracker = new MatomoTracker(configuration)) {\n            tracker.sendBulkRequestAsync(MatomoRequests\n                    .ecommerceCartUpdate(50.0)\n                    .ecommerceItems(EcommerceItems\n                            .builder()\n                            .item(EcommerceItem\n                                    .builder()\n                                    .sku(\"XYZ12345\")\n                                    .name(\"Matomo - The big book about web analytics\")\n                                    .category(\"Education \u0026 Teaching\")\n                                    .price(23.1)\n                                    .quantity(2)\n                                    .build())\n                            .item(EcommerceItem\n                                    .builder()\n                                    .sku(\"B0C2WV3MRJ\")\n                                    .name(\"Matomo for data visualization\")\n                                    .category(\"Education \u0026 Teaching\")\n                                    .price(15.0)\n                                    .quantity(1)\n                                    .build())\n                            .build())\n                    .visitorId(VisitorId.fromString(\"customer@mail.com\"))\n                    .build()\n            );\n        } catch (Exception e) {\n            throw new RuntimeException(\"Could not close tracker\", e);\n        }\n\n    }\n\n}\n```\n\nNote that if you want to be able to track campaigns using *Referrers \u0026gt; Campaigns*, you must add the correct\nURL parameters to your actionUrl. See [Tracking Campaigns](https://matomo.org/docs/tracking-campaigns/) for more\ninformation. All HTTP query parameters\ndenoted on the [Matomo Tracking HTTP API](https://developer.matomo.org/api-reference/tracking-api) can be set using the\nappropriate getters and setters. See\n[MatomoRequest](core/src/main/java/org/matomo/java/tracking/MatomoRequest.java) for the mappings of the parameters to\ntheir corresponding attributes.\n\nRequests are validated prior to sending. If a request is invalid, a `MatomoException` will be thrown.\n\nIn a Servlet environment, it might be easier to use the `ServletMatomoRequest` class to create a `MatomoRequest` from a\n`HttpServletRequest`:\n\n```java\nimport jakarta.servlet.http.HttpServletRequest;\nimport org.matomo.java.tracking.MatomoRequest;\nimport org.matomo.java.tracking.MatomoRequests;\nimport org.matomo.java.tracking.MatomoTracker;\nimport org.matomo.java.tracking.parameters.VisitorId;\nimport org.matomo.java.tracking.servlet.JakartaHttpServletWrapper;\nimport org.matomo.java.tracking.servlet.ServletMatomoRequest;\n\npublic class ServletMatomoRequestExample {\n\n    private final MatomoTracker tracker;\n\n    public ServletMatomoRequestExample(MatomoTracker tracker) {\n        this.tracker = tracker;\n    }\n\n    public void someControllerMethod(HttpServletRequest request) {\n        MatomoRequest matomoRequest = ServletMatomoRequest\n                .addServletRequestHeaders(\n                        MatomoRequests.contentImpression(\n                                \"Latest Product Announced\",\n                                \"Main Blog Text\",\n                                \"https://www.yourdomain.com/blog/2018/10/01/new-product-launches\"\n                        ),\n                        JakartaHttpServletWrapper.fromHttpServletRequest(request)\n                ).visitorId(VisitorId.fromString(\"customer@mail.com\"))\n                // ...\n                .build();\n        tracker.sendRequestAsync(matomoRequest);\n        // ...\n    }\n\n}\n```\n\nThe `ServletMatomoRequest` automatically sets the action URL, applies browser request headers, corresponding Matomo\ncookies and the visitor IP address. It sets the visitor ID, Matomo session ID, custom variables and heatmap\nif Matomo cookies are present. Since there was a renaming from Java EE (javax) to Jakarta EE (jakarta), we provide a\nwrapper class `JakartaHttpServletWrapper` for Jakarta and `JavaxHttpServletWrapper` for javax.\n\n### Tracking Configuration\n\nThe `MatomoTracker` can be configured using the `TrackerConfiguration` object. The following configuration options are\navailable:\n\n* `.apiEndpoint(...)` An `URI` object that points to the Matomo Tracking API endpoint of your Matomo installation. Must\n  be set.\n* `.defaultSiteId(...)` If you provide a default site id, it will be taken if the action does not contain a site id.\n* `.defaultTokenAuth(...)` If you provide a default token auth, it will be taken if the action does not contain a token\n  auth.\n* `.enabled(...)` The tracker is enabled per default. You can disable it per configuration with this flag.\n* `.logFailedTracking(...)` Will send errors to the log if the Matomo Tracking API responds with an erroneous HTTP code\n* `.connectTimeout(...)` allows you to change the default connection timeout of 10 seconds. 0 is\n  interpreted as infinite, null uses the system default\n* `.socketTimeout(...)` allows you to change the default socket timeout of 10 seconds. 0 is\n  interpreted as infinite, null uses the system default\n* `.userAgent(...)` used by the request made to the endpoint is `MatomoJavaClient` per default. You can change it by\n  using this builder method.\n* `.proxyHost(...)` The hostname or IP address of an optional HTTP proxy. `proxyPort` must be\n  configured as well\n* `.proxyPort(...)` The port of an HTTP proxy. `proxyHost` must be configured as well.\n* `.proxyUsername(...)` If the HTTP proxy requires a username for basic authentication, it can be\n  configured with this method. Proxy host, port and password must also be set.\n* `.proxyPassword(...)` The corresponding password for the basic auth proxy user. The proxy host,\n  port and username must be set as well.\n* `.disableSslCertValidation(...)` If set to true, the SSL certificate of the Matomo server will not be validated. This\n  should only be used for testing purposes. Default: false\n* `.disableSslHostVerification(...)` If set to true, the SSL host of the Matomo server will not be validated. This\n  should only be used for testing purposes. Default: false\n* `.threadPoolSize(...)` The number of threads that will be used to asynchronously send requests. Default: 2\n\n## Migration from Version 2 to 3\n\nWe improved this library by adding the dimension parameter and removing outdated parameters in Matomo version 5,\nremoving some dependencies (that even contained vulnerabilities) and increasing maintainability. Sadly this includes the\nfollowing breaking changes:\n\n### Removals\n\n* The parameter `actionTime` (`gt_ms`) is no longer supported by Matomo 5 and was removed.\n* Many methods marked as deprecated in version 2 were removed. Please see the\n  former [Javadoc](https://javadoc.io/doc/org.piwik.java.tracking/matomo-java-tracker/2.1/index.html) of version 2 to\n  get the\n  deprecated methods.\n* We removed the vulnerable dependency to the Apache HTTP client. Callbacks are no longer of\n  type `FutureCallback\u003cHttpResponse\u003e`, but\n  `Consumer\u003cVoid\u003e` instead.\n* The `send...` methods of `MatomoTracker` no longer return a value (usually Matomo always returns an HTTP 204 response\n  without a body). If the request fails, an exception will be thrown.\n* Since there are several ways on how to set the auth token, `verifyAuthTokenSet` was removed. Just check yourself,\n  whether your auth token is null. However, the tracker checks, whether an auth token is either set by parameter, by\n  request or per configuration.\n* Due to a major refactoring on how the queries are created, we no longer use a large map instead of concrete attributes\n  to collect the Matomo parameters. Therefore `getParameters()` of class `MatomoRequest` no longer exists. Please use\n  getters and setters instead.\n* The methods `verifyEcommerceEnabled()` and `verifyEcommerceState()` were removed from `MatomoRequest`. The request\n  will be validated prior to sending and not during construction.\n* `getRandomHexString` was removed. Use `RandomValue.random()` or `VisitorId.random()` instead.\n\n### Type Changes and Renaming\n\n* `requestDatetime`, `visitorPreviousVisitTimestamp`, `visitorFirstVisitTimestamp`, `ecommerceLastOrderTimestamp` are\n  of type `Instant`. You can use `Instant.ofEpochSecond()` to create\n  them from epoch seconds.\n* `requestDatetime` was renamed to `requestTimestamp` due to setter collision and downwards compatibility\n* `goalRevenue` is the same parameter as `ecommerceRevenue` and was removed to prevent duplication.\n  Use `ecommerceRevenue` instead.\n* `setEventValue` requires a double parameter\n* `setEcommerceLastOrderTimestamp` requires an `Instant` parameter\n* `headerAcceptLanguage` is of type `AcceptLanguage`. You can build it easily\n  using `AcceptLanguage.fromHeader(\"de\")`\n* `visitorCountry` is of type `Country`. You can build it easily using `AcceptLanguage.fromCode(\"fr\")`\n* `deviceResolution` is of type `DeviceResolution`. You can build it easily\n  using `DeviceResolution.builder.width(...).height(...).build()`. To easy the migration, we added a constructor\n  method `DeviceResolution.fromString()` that accepts inputs of kind _width_x_height_, e.g. `100x200`\n* `pageViewId` is of type `UniqueId`. You can build it easily using `UniqueId.random()`\n* `randomValue` is of type `RandomValue`. You can build it easily using `RandomValue.random()`. However, if you\n  really\n  want to insert a custom string here, use `RandomValue.fromString()` construction method.\n* URL was removed due to performance and complicated exception handling and problems with parsing of complex\n  URLs. `actionUrl`, `referrerUrl`, `outlinkUrl`, `contentTarget` and `downloadUrl` are strings.\n* `getCustomTrackingParameter()` of `MatomoRequest` returns an unmodifiable list.\n* Instead of `IllegalStateException` the tracker throws `MatomoException`\n* In former versions the goal id had always to be zero or null. You can define higher numbers than zero.\n* For more type changes see the sections below.\n\n### Visitor ID\n\n* `visitorId` and `visitorCustomId` are of type `VisitorId`. You can build them easily\n  using `VisitorId.fromHash(...)`.\n* You can use `VisitorId.fromHex()` to create a `VisitorId` from a string that contains only hexadecimal characters.\n* Or simply use `VisitorId.fromUUID()` to create a `VisitorId` from a `UUID` object.\n* VisitorId.fromHex() supports less than 16 hexadecimal characters. If the string is shorter than 16 characters,\n  the remaining characters will be filled with zeros.\n\n### Custom Variables\n\n* According to Matomo, custom variables should no longer be used. Please use dimensions instead. Dimension support has\n  been introduced.\n* `CustomVariable` is in package `org.matomo.java.tracking.parameters`.\n* `customTrackingParameters` in `MatomoRequestBuilder` requires a `Map\u003cString, Collection\u003cString\u003e\u003e` instead\n  of `Map\u003cString, String\u003e`\n* `pageCustomVariables` and `visitCustomVariables` are of type `CustomVariables` instead of collections. Create them\n  with `new CustomVariables().add(customVariable)`\n* `setPageCustomVariable` and `getPageCustomVariable` no longer accept a string as an index. Please use integers\n  instead.\n* Custom variables will be sent URL encoded\n\n## Building and testing\n\nThis project can be tested and built by calling\n\n```shell\nmvn install\n```\n\nThe built jars and javadoc can be found in `target`. By using\nthe Maven goal `install, a snapshot\nversion can be used in your local Maven repository for testing purposes, e.g.\n\n```xml\n\u003cdependency\u003e\n    \u003cgroupId\u003eorg.piwik.java.tracking\u003c/groupId\u003e\n    \u003cartifactId\u003ematomo-java-tracker\u003c/artifactId\u003e\n    \u003cversion\u003e3.4.1-SNAPSHOT\u003c/version\u003e\n\u003c/dependency\u003e\n```\n\n## Testing on a local Matomo instance\n\nTo start a local Matomo instance for testing, you can use the docker-compose file in the root directory of this project.\nStart the docker containers with\n\n```shell\ndocker-compose up -d\n```\n\nYou need to adapt your config.ini.php file and change\nthe following line:\n\n```ini\n[General]\ntrusted_hosts[] = \"localhost:8080\"\n```\n\nto\n\n```ini\n[General]\ntrusted_hosts[] = \"localhost:8080\"\n```\n\nAfter that you can access Matomo at http://localhost:8080. You have to set up Matomo first. The database credentials are\n`matomo` and `matomo`. The database name is `matomo`. The (internal) database host address is `database`. The database\nport is `3306`. Set the URL to http://localhost and enable ecommerce.\n\nThe following snippets helps you to do this quickly:\n\n```shell\ndocker-compose exec matomo sed -i 's/localhost/localhost:8080/g' /var/www/html/config/config.ini.php\n```\n\nAfter the installation you can run `MatomoTrackerTester` in the module `test` to test the tracker. It will send\nmultiple randomized\nrequests to the local Matomo instance.\n\nTo enable debug logging, you append the following line to the `config.ini.php` file:\n\n```ini\n[Tracker]\ndebug = 1\n```\n\nUse the following snippet to do this:\n\n```shell\ndocker-compose exec matomo sh -c 'echo -e \"\\n\\n[Tracker]\\ndebug = 1\\n\" \u003e\u003e /var/www/html/config/config.ini.php'\n```\n\nTo test the servlet integration, run `MatomoServletTester` in your favorite IDE. It starts an embedded Jetty server\nthat serves a simple servlet. The servlet sends a request to the local Matomo instance if you call the URL\nhttp://localhost:8090/track.html. Maybe you need to disable support for the Do Not Track preference in Matomo to get the\nrequest tracked: Go to _Administration \u0026gt; Privacy \u0026gt; Do Not Track_ and disable the checkbox _Respect Do Not Track.\nWe also recommend to install the Custom Variables plugin from Marketplace to the test custom variables feature and\nsetup some dimensions.\n\n## Versioning\n\nWe use [SemVer](https://semver.org/) for versioning. For the versions available, see\nthe [tags on this repository](https://github.com/matomo-org/matomo-java-tracker/tags).\n\n## Contribute\n\nHave a fantastic feature idea? Spot a bug? We would absolutely love for you to contribute to this project!  Please feel\nfree to:\n\n* Fork this project\n* Create a feature branch from the _master_ branch\n* Write awesome code that does awesome things\n* Write awesome test to test your awesome code\n* Verify that everything is working as it should by running _mvn test_. If everything passes, you may\n  want to make sure that your tests are covering everything you think they are!\n  Run `mvn verify` to find out!\n* Commit this code to your repository\n* Submit a pull request from your branch to our dev branch and let us know why you made the changes you did\n* We'll take a look at your request and work to get it integrated with the repo!\n\nPlease read [the contribution document](CONTRIBUTING.md) for details on our code of conduct, and the\nprocess for submitting pull requests to us.\n\nWe use Checkstyle and JaCoCo to ensure code quality. Please run `mvn verify` before submitting a pull request. Please\nprovide tests for your changes. We use JUnit 5 for testing. Coverage should be at least 80%.\n\n## Other Java Matomo Tracker Implementations\n\n* [The original Piwik Java Tracker Implementation](https://github.com/summitsystemsinc/piwik-java-tracking)\n* [Matomo SDK for Android](https://github.com/matomo-org/matomo-sdk-android)\n* [Piwik SDK Android]( https://github.com/lkogler/piwik-sdk-android)\n* [piwik-tracking](https://github.com/ralscha/piwik-tracking)\n* [Matomo Tracking API Java Client](https://github.com/dheid/matomo-tracker) -\u003e Most of the code was integrated in the\n  official Matomo Java Tracker\n\n## License\n\nThis software is released under the BSD 3-Clause license. See [LICENSE](LICENSE).\n\n## Copyright\n\nCopyright (c) 2015 General Electric Company. All rights reserved.\n\n\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmatomo-org%2Fmatomo-java-tracker","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmatomo-org%2Fmatomo-java-tracker","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmatomo-org%2Fmatomo-java-tracker/lists"}