Skip to content

Commit 6ae7320

Browse files
sgiehlsgiehl
authored
Merge pull request #767 from dheid/live
Add Matomo Java Tracker documentation
2 parents 33bc2fb + ed78563 commit 6ae7320

File tree

5 files changed

+411
-2
lines changed

5 files changed

+411
-2
lines changed

‎app/helpers/Content/Category/ApiReferenceCategory.php

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -44,6 +44,7 @@ public function getItems()
4444
new EmptySubCategory('Tracking', [
4545
new ApiReferenceGuide('tracking-api'),
4646
new ApiReferenceGuide('tracking-javascript'),
47+
new ApiReferenceGuide('tracking-java'),
4748
new PhpDoc($matomoTracker, 'PHP-Matomo-Tracker', 'PHP Tracking Client'),
4849
]),
4950
new EmptySubCategory('Tag Manager', [

‎docs/4.x/api-reference-introduction.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,4 +6,4 @@ title: Introduction
66

77
The API Reference contains low-level details on Piwik APIs and codebase.
88

9-
You will find here documentation on Piwik's HTTP APIs, JavaScript client and PHP classes, methods and hooks.
9+
You will find here documentation on Piwik's HTTP APIs, JavaScript client, Java and PHP classes, methods and hooks.

‎docs/4.x/tracking-java.md

Lines changed: 204 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,204 @@
1+
---
2+
category: API Reference
3+
---
4+
# Java Tracker
5+
6+
The Matomo Java Tracker is a Java library to send tracking data to Matomo servers. It is compatible with Java 1.8 and above. You can use it to track data from any Java application, including Java web applications, Java desktop applications, Java command line applications, Java batch applications, Java microservices and more.
7+
8+
Due to the nature of Java applications, the API is different from the JavaScript Tracker API. Nevertheless it supports synchronous and asynchronous tracking, custom dimensions, custom variables, custom events, content tracking, ecommerce tracking, goal tracking, site search tracking, campaign tracking, and more.
9+
10+
The primary source to look for an API documentation is the [JavaDoc](https://matomo-org.github.io/matomo-java-tracker/javadoc/index.html). This guide provides a quick overview of the most important classes and methods of the library.
11+
12+
If you experience any problems or have any questions, please [create an issue](https://github.com/matomo-org/matomo-java-tracker/issues/new) in the [Matomo Java Tracker repository](https://github.com/matomo-org/matomo-java-tracker). We are happy to help you.
13+
14+
## Adding the dependency
15+
16+
To use the Matomo Java Tracker in your Java application, you need to add the dependency to your project. The library is available on Maven Central:
17+
18+
```xml
19+
<dependency>
20+
<groupId>org.piwik.java.tracking</groupId>
21+
<artifactId>matomo-java-tracker</artifactId>
22+
<version>3.x.x</version>
23+
</dependency>
24+
```
25+
26+
Gradle users add the following dependency to their `build.gradle` file:
27+
28+
```groovy
29+
implementation 'org.piwik.java.tracking:matomo-java-tracker:3.x.x'
30+
```
31+
32+
## TrackerConfiguration
33+
34+
The class `TrackerConfiguration` configures the tracker and can be built in a fluent way. See the configuration properties in the [JavaDoc of TrackerConfiguration](https://matomo-org.github.io/matomo-java-tracker/javadoc/org/matomo/java/tracking/TrackerConfiguration.html).
35+
36+
To create a tracker configuration fluently you can use the `TrackerConfiguration.builder()` method:
37+
38+
```java
39+
TrackerConfiguration configuration = TrackerConfiguration.builder()
40+
.apiEndpoint(URI.create("https://your-domain.net/matomo/matomo.php"))
41+
.defaultSiteId(42) // if not explicitly specified by the request
42+
.build();
43+
```
44+
45+
In this example the tracker will send the tracking requests to the Matomo server at `https://your-domain.net/matomo/matomo.php` and use the site id `42`. The tracker will use the default values for all other configuration properties.
46+
47+
## MatomoTracker
48+
49+
The class `MatomoTracker` is the main class to use when sending tracking requests. It contains methods to send tracking requests synchronously and asynchronously.
50+
51+
```java
52+
MatomoTracker tracker = new MatomoTracker(configuration);
53+
tracker.sendBulkRequestAsync(requests);
54+
```
55+
56+
In this example the tracker sends a bulk request asynchronously. The tracker will send the requests in the background and return immediately. The tracker will use the configuration set in the constructor to send the requests via HTTP POST.
57+
58+
Don't create the `MatomoTracker` on each tracking request, since it's thread-safe and stateless. Create it once and reuse it for multiple tracking requests.
59+
60+
We recommend to use the method `MatomoTracker.sendBulkRequestAsync(Collection<MatomoRequest>)` to send tracking requests asynchronously. If you want to send requests synchronously, you can use the method `MatomoTracker.sendBulkRequest(Collection<MatomoRequest>)`. Both methods will send the requests in a single HTTP request. If you want to send the requests in multiple HTTP GET requests, you can use the method `MatomoTracker.sendRequest(MatomoRequest)` or `MatomoTracker.sendRequestAsync(MatomoRequest)` to send a single request.
61+
62+
## MatomoRequest
63+
64+
The class `MatomoRequest` represents a single tracking request. It is the main class to use when collecting data. It contains methods to set all parameters of a Matomo tracking request. The following example shows how to create a new Matomo tracking request fluently:
65+
66+
```java
67+
MatomoRequest request = MatomoRequest.request()
68+
.url("https://example.com")
69+
.actionName("My Action")
70+
.build();
71+
```
72+
73+
Nevertheless we strongly recommend you to use one of the methods of the class `MatomoRequests` to track:
74+
75+
1. **action(@NonNull String url, @NonNull ActionType type):**
76+
- Creates a `MatomoRequest` object for a download or a link action.
77+
2. **contentImpression(@NonNull String name, String piece, String target):**
78+
- Creates a `MatomoRequest` object for a content impression.
79+
3. **contentInteraction(@NonNull String interaction, @NonNull String name, String piece, String target):**
80+
- Creates a `MatomoRequest` object for a content interaction.
81+
4. **crash(@NonNull String message, String type, String category, String stackTrace, String location, Integer line, Integer column):**
82+
- Creates a `MatomoRequest` object for a crash with specified details.
83+
5. **crash(@NonNull Throwable throwable, String category):**
84+
- Creates a `MatomoRequest` object for a crash with information extracted from a `Throwable` object.
85+
6. **ecommerceCartUpdate(@NonNull Double revenue):**
86+
- Creates a `MatomoRequest` object for an ecommerce cart update (add item, remove item, update item).
87+
7. **ecommerceOrder(@NonNull String id, @NonNull Double revenue, Double subtotal, Double tax, Double shippingCost, Double discount):**
88+
- Creates a `MatomoRequest` object for an ecommerce order.
89+
8. **event(@NonNull String category, @NonNull String action, String name, Double value):**
90+
- Creates a `MatomoRequest` object for an event.
91+
9. **goal(int id, Double revenue):**
92+
- Creates a `MatomoRequest` object for a conversion of a goal on the website.
93+
10. **pageView(@NonNull String name):**
94+
- Creates a `MatomoRequest` object for a page view.
95+
11. **ping():**
96+
- Creates a `MatomoRequest` object for a ping.
97+
12. **siteSearch(@NonNull String query, String category, Long resultsCount):**
98+
- Creates a `MatomoRequest` object for a search.
99+
100+
Example:
101+
102+
```java
103+
MatomoRequest request = MatomoRequests
104+
.pageView("My Page")
105+
.build();
106+
```
107+
108+
Please mind that the ecommerce parameters can only be set if a goal id is also set. Search results count requires a search query. The visitor location parameters (like longitude, latitude, city, country, etc.) require an authentication token.
109+
110+
Here is complete example that shows how to create a tracker configuration, instantiate a tracker and send a request:
111+
112+
```java
113+
// Create the tracker configuration
114+
TrackerConfiguration configuration = TrackerConfiguration.builder()
115+
.apiEndpoint(URI.create("https://your-domain.net/matomo/matomo.php"))
116+
.defaultSiteId(42) // if not explicitly specified by action
117+
.build();
118+
119+
// Prepare the tracker (stateless - can be used for multiple requests)
120+
MatomoTracker tracker = new MatomoTracker(configuration);
121+
122+
MatomoRequest request = MatomoRequests
123+
.event("Training", "Workout completed", "Bench press", 60.0)
124+
.visitorId(VisitorId.fromString("[email protected]"))
125+
// ...
126+
.build();
127+
128+
// Send the request asynchronously (non-blocking) as an HTTP POST request (payload is JSON and contains the
129+
// tracking parameters)
130+
tracker.sendBulkRequestAsync(request);
131+
132+
```
133+
134+
This example configures the tracker to send the tracking requests to the Matomo server at `https://example.com/matomo.php` and use the site id `42`. The tracker will use the default values for all other configuration properties. The request sets the action name and action URL. It also sets a custom visitor id. The tracker will send the request asynchronously and return immediately. The tracker will use the configuration set in the constructor to send the requests via HTTP POST. Using the method `CompletableFuture.join()` you can wait for the request to be sent. If the request fails, the method will throw an unchecked exception.
135+
136+
## Authentikation Token
137+
138+
The parameter `token_auth` contains the authentication token of the Matomo user. Some parameters require it. The authorization key can be found in the Matomo user interface under "Administration" -> "Personal" -> "Security" -> "Auth tokens"
139+
140+
Using the Matomo Java Tracker are three different ways to set the authentication token:
141+
142+
1. Set the authentication token globally in the tracker configuration. The authentication token will be used for all tracking requests. The authorization key can be set using the method `TrackerConfiguration.builder().defaultTokenAuth(String)`.
143+
144+
2. Set the authentication token in the tracking request. The authentication token will be used for this tracking request only. The authorization key can be set using the method `MatomoRequest.request().authToken(String)`.
145+
146+
3. (Deprecated) Call a send method of the tracker with the authentication token as a parameter. The authentication token will be used for this tracking request only. Since this method is redundant, it is deprecated and will be removed in a future version. It has the same effect than setting it in the request. Set it in the request or globally instead.
147+
148+
The tracker uses primarily the authentication set via method parameter, then the authentication set in the request, and finally the authentication set in the tracker configuration. If no authentication token is set, the tracker won't set the parameter `token_auth` in the tracking request. This can lead to problems if you use parameters that require an authentication token. In this case, the tracker will throw an exception on sending the request.
149+
150+
Please mind that the token should be transmitted securely, for example using HTTPS.
151+
152+
## Custom Tracking Parameters
153+
154+
You can also set additional custom request parameters using the method `MatomoRequest.request().additionalParameters(Map<String, Collection<Object>>)`. The additional parameters will be added to the request URL as query parameters. The query parameter name will be the key of the map entry and the query parameter value will be the value of the map entry. To add the same query parameter name with multiple values, you can use a collection as the parameter value, e.g. `additionalParameters(Map.of("foo", List.of("bar", "baz")))` will add the query parameters `?foo=bar&foo=baz` to the request URL (note that the order of the query parameters is not guaranteed). Note: If you set any parameter that is not supported by the Matomo tracking API, the parameter will be ignored by Matomo, although it will be added to the request URL.
155+
156+
To see which parameters are available, have a look at the [JavaDoc of MatomoRequest](https://matomo-org.github.io/matomo-java-tracker/javadoc/org/matomo/java/tracking/MatomoRequest.html) and the [Matomo Tracking API Reference](https://developer.matomo.org/api-reference/tracking-api) for your Matomo version.
157+
158+
## Ecommerce Items
159+
160+
Matomo supports ecommerce tracking, i.e. tracking of ecommerce actions like adding items to the cart, removing items from the cart, and purchasing items. Every ecommerce action can be tracked as a goal. To track ecommerce actions, you need to set a goal id in the request. You can set the goal id using the method `MatomoRequest.request().goalId(int)`. The goal id is the id of the goal in Matomo. You can find the goal id in the Matomo user interface under "Administration" -> "Websites" -> "Goals". The goal id is the number in the URL of the edit page.
161+
162+
Ecommerce items can be added to a request using the method `MatomoRequest.request().ecommerceItems(EcommerceItems)`. The items will be added to the request URL as a JSON representation in the query parameter `ec_items`. The JSON representation is an array of JSON objects. Each JSON object represents an ecommerce item. Ecommerce items are only supported if a goal id is set in the request. If you set ecommerce items without a goal id, the items will be ignored by Matomo.
163+
164+
To create an ecommerce items object, you can use the builder `EcommerceItems.builder()`:
165+
166+
```java
167+
MatomoRequests
168+
.ecommerceCartUpdate(50.0)
169+
.ecommerceItems(EcommerceItems
170+
.builder()
171+
.item(EcommerceItem
172+
.builder()
173+
.sku("XYZ12345")
174+
.name("Matomo - The big book about web analytics")
175+
.category("Education & Teaching")
176+
.price(23.1)
177+
.quantity(2)
178+
.build())
179+
.item(EcommerceItem
180+
.builder()
181+
.sku("B0C2WV3MRJ")
182+
.name("Matomo for data visualization")
183+
.category("Education & Teaching")
184+
.price(15.0)
185+
.quantity(1)
186+
.build())
187+
.build();
188+
```
189+
190+
## Custom Variables
191+
192+
Matomo supports custom variables. Custom variables are key-value pairs that can be used to track additional information about the visitor. Custom variables can be set in the request using the method `MatomoRequest.request().visitCustomVariables(CustomVariables)`. The custom variables will be added to the request URL as a JSON representation in the query parameter `cvar`. The JSON representation is an array of JSON objects. Each JSON object represents a custom variable.
193+
194+
To create a custom variables object use the constructor `new CustomVariables()` and add custom variables using the method `CustomVariables.add(String, String)`:
195+
196+
```java
197+
CustomVariables customVariables = new CustomVariables()
198+
.add(new CustomVariable("Type", "Customer"), 1)
199+
.add(new CustomVariable("Status", "Logged In"), 3);
200+
```
201+
202+
The first parameter contains the custom variable consisting of the key and the value. The second parameter contains the index of the custom variable. The index is used to identify the variable in the Matomo user interface. You can find the custom variables in the Matomo user interface under "Visitors" -> "Custom Variables". The index is the number in the URL of the custom variables page.
203+
204+
The class `MatomoRequest` has two different custom variables attributes: `visitCustomVariables` and `pageCustomVariables`. The `visitCustomVariables` attribute contains the custom variables for the visit. The `pageCustomVariables` attribute contains the custom variables for the page. The difference is that the `visitCustomVariables` attribute is set in the visit scope and the `pageCustomVariables` attribute is set in the page scope. The visit scope means that the custom variables are valid for the whole visit. The page scope means that the custom variables are valid for the current page only.

‎docs/5.x/api-reference-introduction.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,4 +6,4 @@ title: Introduction
66

77
The API Reference contains low-level details on Piwik APIs and codebase.
88

9-
You will find here documentation on Piwik's HTTP APIs, JavaScript client and PHP classes, methods and hooks.
9+
You will find here documentation on Piwik's HTTP APIs, JavaScript client, PHP and Java classes, methods and hooks.

0 commit comments

Comments
 (0)