2.1、Java 集成 Matomo - Powered by MinDoc

Matomo Java Tracker

https://developer.matomo.org/api-reference/tracking-java

Matomo Java Tracker 是一个全面的 Java 库，旨在将跟踪数据发送到 Matomo 服务器。它与 Java 1.8 及更高版本兼容。无论您使用的是 Java Web 应用程序、桌面应用程序、命令行应用程序、批处理应用程序、微服务还是其他基于 Java 的项目，Matomo Java Tracker 都能满足您的需求。

由于 Java 应用程序的独特特性，它与 JavaScript Tracker API 不同。该库为同步和异步跟踪提供了强大的支持。它有助于跟踪自定义维度、自定义变量、自定义事件、内容、电子商务活动、目标、网站搜索、广告活动等。

有关详细的 API 文档，请参阅JavaDoc。该文档简要、详尽地概述了库中的基本类和方法。

如果您遇到任何挑战或有疑问，请随时在Matomo Java Tracker 存储库中创建问题。我们的团队很乐意为您提供帮助。

添加依赖项

要将 Matomo Java Tracker 集成到 Java 应用程序中，您必须在项目中包含必要的依赖项。可以从 Maven Central 轻松获取该库：

<dependency>
    <groupId>org.piwik.java.tracking</groupId>
    <artifactId>matomo-java-tracker</artifactId>
    <version>3.x.x</version>
</dependency>

Gradle 用户将以下依赖项添加到他们的build.gradle文件中：

implementation 'org.piwik.java.tracking:matomo-java-tracker:3.x.x'

追踪器配置

该类TrackerConfiguration配置跟踪器，可以流畅地构建。请参阅TrackerConfiguration 的 JavaDoc中的配置属性。

要流畅地创建跟踪器配置，您可以使用以下TrackerConfiguration.builder()步骤：

TrackerConfiguration configuration = TrackerConfiguration.builder()
        .apiEndpoint(URI.create("https://your-domain.net/matomo/matomo.php"))
        .defaultSiteId(42) // if not explicitly specified by the request
        .build();

在此示例中，跟踪器将向 Matomo 服务器发送跟踪请求https://your-domain.net/matomo/matomo.php 并使用站点 ID 42。跟踪器将对所有其他配置属性使用默认值。

Matomo追踪器

该类MatomoTracker 是用于发送跟踪请求的主要类。它包含同步和异步发送跟踪请求的方法。

MatomoTracker tracker = new MatomoTracker(configuration);
tracker.sendBulkRequestAsync(requests);

在此示例中，跟踪器执行异步批量请求，从而实现在后台并发传输请求并迅速返回控制权。构造函数中指定的配置指导跟踪器利用 HTTP POST 无缝调度请求。

避免为每个跟踪请求创建一个新的MatomoTracker，因为它是线程安全的和无状态的。创建一次即可在多个跟踪请求中重复使用。

我们建议使用方法MatomoTracker.sendBulkRequestAsync(Collection)来异步发送跟踪请求。如果您想同步发送请求，可以使用方法来发送MatomoTracker.sendBulkRequest(Collection)。这两种方法都会在单个 HTTP 请求中发送请求。如果您想在多个 HTTP GET 请求中发送请求，您可以使用方法MatomoTracker.sendRequest(MatomoRequest)来MatomoTracker.sendRequestAsync(MatomoRequest)发送单个请求。

Matomo请求
该类MatomoRequest表示单个跟踪请求。它是收集数据时使用的主要类。它包含设置 Matomo 跟踪请求的所有参数的方法。以下示例显示如何流畅地创建新的 Matomo 跟踪请求：

MatomoRequest request = MatomoRequest.request().url(“https://example.com").actionName(“My Action”).build();
尽管如此，我们强烈建议您使用该类的其中一种方法MatomoRequests 来跟踪：

action(@NonNull String url, @NonNull ActionType type)：MatomoRequest为下载或链接操作创建一个对象。
contentImpression(@NonNull String name, String piece, String target)：MatomoRequest为内容印象创建一个对象。
contentInteraction(@NonNull String interaction, @NonNull String name, String piece, String target)：MatomoRequest为内容交互创建一个对象。
crash(@NonNull String message, String type, String category, String stackTrace, String location, Integer line, Integer column)：MatomoRequest使用指定的详细信息为崩溃创建一个对象。
crash(@NonNull Throwable throwable，String category)：MatomoRequest使用从对象中提取的信息为崩溃创建一个对象Throwable。
ecommerceCartUpdate(@NonNull Double revenue)：MatomoRequest为电子商务购物车更新（添加商品、删除商品、更新商品）创建一个对象。
ecommerceOrder(@NonNull String id, @NonNull Double revenue, Double subtotal, Double tax, Double shippingCost, Double discount)：MatomoRequest为电子商务订单创建一个对象。
event(@NonNull String category, @NonNull String action, String name, Double value):MatomoRequest为事件创建一个对象。
goal(int id，Double revenue)：MatomoRequest为网站上的目标转换创建一个对象。
pageView(@NonNull String name)：MatomoRequest为页面视图创建一个对象。
ping()：MatomoRequest为 ping创建一个对象。
siteSearch(@NonNull String query, String category, Long resultsCount)：MatomoRequest为搜索创建一个对象。
例子：

MatomoRequest request = MatomoRequests.pageView(“My Page”).build();
搜索结果计数需要搜索查询。访客位置参数（如经度、纬度、城市、国家等）需要身份验证令牌。

下面是一个完整的示例，展示了如何创建跟踪器配置、实例化跟踪器并发送请求：

// Create the tracker configuration
TrackerConfiguration configuration = TrackerConfiguration.builder()
.apiEndpoint(URI.create(“https://your-domain.net/matomo/matomo.php"))
.defaultSiteId(42) // if not explicitly specified by action
.build();

// Prepare the tracker (stateless - can be used for multiple requests)
MatomoTracker tracker = new MatomoTracker(configuration);

MatomoRequest request = MatomoRequests
.event(“Training”,”Workout completed”,”Bench press”,60.0)
.visitorId(VisitorId.fromString(“@email-adress.org"">some@email-adress.org“))
// …
.build();

// Send the request asynchronously (non-blocking) as an HTTP POST request (payload is JSON and contains the
// tracking parameters)
tracker.sendBulkRequestAsync(request);
此示例配置跟踪器将跟踪请求发送到 Matomo 服务器https://example.com/matomo.php并使用站点 ID 42。跟踪器将使用所有其他配置属性的默认值。请求设置操作名称和操作 URL。它还设置自定义访问者 ID。跟踪器将异步发送请求并立即返回。跟踪器将使用构造函数中设置的配置通过 HTTP POST 发送请求。使用该方法，CompletableFuture.join()您可以等待请求发送。如果请求失败，该方法将抛出未经检查的异常。

身份验证令牌
该token_auth参数包含 Matomo 用户的身份验证令牌。有些参数需要它。授权密钥可以在 Matomo 用户界面的“管理”->“个人”->“安全”->“身份验证令牌”下找到

使用 Matomo Java Tracker 有三种不同的方法来设置身份验证令牌：

在跟踪器配置中全局设置身份验证令牌。身份验证令牌将用于所有跟踪请求。可以使用方法设置授权密钥TrackerConfiguration.builder().defaultTokenAuth(String)。

在跟踪请求中设置身份验证令牌。身份验证令牌仅用于此跟踪请求。可以使用方法设置授权密钥MatomoRequest.request().authToken(String)。

（已弃用）使用身份验证令牌作为参数调用跟踪器的发送方法。身份验证令牌将仅用于此跟踪请求。由于此方法是多余的，因此已弃用并将在未来版本中删除。它与在请求中设置它具有相同的效果。请在请求中或全局设置它。

跟踪器主要使用通过方法参数设置的身份验证，然后使用请求中的身份验证，最后使用跟踪器配置中的身份验证。如果没有设置身份验证令牌，跟踪器将不会token_auth在跟踪请求中设置参数。如果您使用需要身份验证令牌的参数，这可能会导致问题。在这种情况下，跟踪器将在发送请求时抛出异常。

确保令牌安全传输，例如使用 HTTPS。

访客 ID
项目中的 VisitorId 类是一个实用程序类，它提供在 Matomo 中创建唯一访客 ID 以进行跟踪的方法。以下是它的使用方法：

根据哈希创建访客 ID：如果您有哈希（例如，用户名的哈希码），则可以使用此 fromHash方法创建访客 ID。此方法始终为同一哈希创建同一访客 ID。 java
VisitorId visitorIdFromHash = VisitorId.fromHash(2389472398L);
通过 UUID 创建访客 ID：如果您有 UUID，则可以使用该fromUUID方法创建访客 ID。此方法使用 UUID 的最高有效位来创建访客 ID。 java
VisitorId visitorIdFromUUID = VisitorId.fromUUID(UUID.fromString(“53e213f2-9a16-4e42-ac6f-5c8637db9fb0”));
从十六进制字符串创建访客 ID：如果您有十六进制字符串，则可以使用此fromHex方法创建访客 ID。输入字符串必须是有效的十六进制字符串，最大长度为 16 个字符。 java
VisitorId visitorIdFromHex = VisitorId.fromHex(“0815badeaffe”);
通过字符串创建访客 ID：如果您有字符串，则可以使用该fromString方法创建访客 ID。此方法对字符串进行哈希处理以创建访客 ID。 java
VisitorId visitorIdFromHex = VisitorId.fromString(“alice”);
自定义跟踪参数
您还可以使用方法设置其他自定义请求参数MatomoRequest.request().additionalParameters(Map<String, Object>)。附加参数将作为查询参数添加到请求 URL。查询参数名称将成为映射条目的键，查询参数值将成为映射条目的值。注意：如果您设置了 Matomo 跟踪 API 不支持的任何参数，Matomo 将忽略该参数，尽管它会被添加到请求 URL。

要查看哪些参数可用，请查看MatomoRequest 的 JavaDoc 和适合您的 Matomo 版本的Matomo 跟踪 API 参考。

电子商务商品
Matomo 支持电子商务跟踪，即跟踪将商品添加到购物车、从购物车中移除商品以及购买商品等电子商务操作。

可以使用方法将电子商务商品添加到请求中MatomoRequest.request().ecommerceItems(EcommerceItems)。这些商品将作为查询参数中的 JSON 表示形式添加到请求 URL。JSONec_items表示形式是 JSON 对象数组。每个 JSON 对象代表一个电子商务商品。

要创建电子商务项目对象，您可以使用构建器EcommerceItems.builder()：

MatomoRequests
.ecommerceCartUpdate(50.0)
.ecommerceItems(EcommerceItems
.builder()
.item(EcommerceItem
.builder()
.sku(“XYZ12345”)
.name(“Matomo - The big book about web analytics”)
.category(“Education & Teaching”)
.price(23.1)
.quantity(2)
.build())
.item(EcommerceItem
.builder()
.sku(“B0C2WV3MRJ”)
.name(“Matomo for data visualization”)
.category(“Education & Teaching”)
.price(15.0)
.quantity(1)
.build())
.build();
自定义变量
Matomo 支持自定义变量。自定义变量是键值对，可用于跟踪有关访问者的其他信息。可以使用方法在请求中设置自定义变量MatomoRequest.request().visitCustomVariables(CustomVariables)。自定义变量将作为查询参数中的 JSON 表示形式添加到请求 URL。JSONcvar表示形式是 JSON 对象的数组。每个 JSON 对象代表一个自定义变量。

要创建自定义变量对象，请使用构造函数new CustomVariables()并使用该方法添加自定义变量CustomVariables.add(String, String)：

CustomVariables customVariables = new CustomVariables()
.add(new CustomVariable(“Type”, “Customer”), 1)
.add(new CustomVariable(“Status”, “Logged In”), 3);
第一个参数包含由键和值组成的自定义变量。第二个参数包含自定义变量的索引。索引用于在 Matomo 用户界面中识别变量。您可以在 Matomo 用户界面的“访问者”->“自定义变量”下找到自定义变量。索引是自定义变量页面 URL 中的数字。

该类MatomoRequest有两个不同的自定义变量属性：visitCustomVariables 和pageCustomVariables。visitCustomVariables属性包含访问的自定义变量。属性pageCustomVariables包含页面的自定义变量。区别在于属性visitCustomVariables设置在访问范围内，pageCustomVariables属性设置在页面范围内。访问范围意味着自定义变量对整个访问有效。页面范围意味着自定义变量仅对当前页面有效。

Servlet 功能
Matomo Java Tracker 提供跟踪 servlet 中的 HTTP 请求的功能。它支持 Jakarta 和 Javax servlet API。

该类是一个实用程序类，它提供将 Jakarta 转换为JakartaHttpServletWrapper的方法。要将 JakartaHttpServletWrapper 集成到控制器类中，您需要在处理 HTTP 请求的方法中使用它。以下是在 Spring 控制器中执行此操作的示例：HttpServletRequestHttpServletRequestWrapper

import jakarta.servlet.http.HttpServletRequest;
import org.matomo.java.tracking.MatomoRequest;
import org.matomo.java.tracking.MatomoTracker;
import org.matomo.java.tracking.servlet.HttpServletRequestWrapper;
import org.matomo.java.tracking.servlet.JakartaHttpServletWrapper;
import org.matomo.java.tracking.servlet.ServletMatomoRequest;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class MyController {

private final MatomoTracker matomoTracker;

// Injected by your dependency injection framework
public MyController(MatomoTracker matomoTracker) {
this.matomoTracker = matomoTracker;
}

@GetMapping(“/my-endpoint”)
public void handleRequest(HttpServletRequest request) {
// send the request to the Matomo server
matomoTracker.sendRequest(
ServletMatomoRequest.fromServletRequest(
JakartaHttpServletWrapper.fromHttpServletRequest(request))
// add more request parameters if needed
.build()
);
}
}
或者，如果您已经有了MatomoRequestBuilder，并且想要将其中的标题添加到其中HttpServletRequestWrapper ，则可以使用addServletRequestHeaders方法。

ServletMatomoRequest.addServletRequestHeaders(MatomoRequest.builder().actionName(“action”), requestWrapper);
Spring Boot Starter
Matomo Java Tracker Spring Boot Starter 是一个 Maven 工件，它为 Matomo Java Tracker 提供 Spring Boot 集成。它旨在使在 Spring Boot 应用程序中使用 Matomo Java Tracker 变得更加容易。它可能为 Matomo Java Tracker 提供自动配置，并可能提供一些额外的 Spring 特定集成功能。

通过将此工件包含在您的项目内，您可以利用 Spring Boot 的自动配置功能来自动设置和配置 Matomo Java Tracker，从而减少您需要执行的手动配置量。

要将 Matomo Java Tracker Spring Boot Starter 集成到您的 Spring 应用程序中，您需要将其作为依赖项添加到您的 Mavenpom.xml文件中。以下是如何添加它的示例：

<dependency>
    <groupId>org.piwik.java.tracking</groupId>
    <artifactId>matomo-java-tracker-spring-boot-starter</artifactId>
    <version>3.x.x</version> <!-- replace with your desired version -->
</dependency>

matomo.tracker.api-endpoint=https://your-matomo-domain.example/matomo.php
matomo.tracker.default-site-id=1
matomo.tracker.default-auth-token=1234567890abcdef1234567890abcdef
matomo.tracker.enabled=true
matomo.tracker.connect-timeout=10s
matomo.tracker.socket-timeout=30s
matomo.tracker.proxy-host=proxy.example.com
matomo.tracker.proxy-port=8080
matomo.tracker.proxy-username=proxyuser
matomo.tracker.proxy-password=proxypassword
matomo.tracker.user-agent=MatomoJavaClient
matomo.tracker.log-failed-tracking=true
matomo.tracker.disable-ssl-cert-validation=true
matomo.tracker.disable-ssl-host-validation=true
matomo.tracker.thread-pool-size=2
将占位符替换为您的实际值。例如，将 https://your-matomo-domain.example/matomo.php 替换为您的 Matomo 服务器的 URL，并将 1234567890abcdef1234567890abcdef 替换为您的 Matomo 身份验证令牌。完成此操作后，MatomoTracker bean 将自动配置并准备在您的 Spring Boot 应用程序中使用。

作者：Jeebiz 创建时间：2024-11-26 23:12
最后编辑：Jeebiz 更新时间：2024-11-26 23:25

添加依赖项后，您可以在 Spring Boot 应用程序中使用 Matomo Java Tracker Spring Boot Starter 提供的功能。在application.properties或application.yml文件中设置适当的属性。以下是如何在中执行此操作的示例application.properties：