Package org.matomo.java.tracking

Class MatomoTracker

java.lang.Object
org.matomo.java.tracking.MatomoTracker
Direct Known Subclasses:
PiwikTracker
public class MatomoTracker extends Object
The main class that sends MatomoRequests to a specified Matomo server.

Contains several methods to send requests synchronously and asynchronously. The asynchronous methods return a CompletableFuture that can be used to wait for the request to finish. The synchronous methods block until the request is finished. The asynchronous methods are more efficient if you want to send multiple requests at once.

Configure this tracker using the TrackerConfiguration class. You can use the TrackerConfiguration.builder() to create a new configuration. The configuration is immutable and can be reused for multiple trackers.

The tracker is thread-safe and can be used by multiple threads at once.

Author:
brettcsorba

  • Constructor Details

    • MatomoTracker

      @Deprecated public MatomoTracker(@NonNull @NonNull String hostUrl)
      Deprecated.
      Please use MatomoTracker(TrackerConfiguration)
      Creates a tracker that will send MatomoRequests to the specified Tracking HTTP API endpoint.
      Parameters:
      hostUrl - url endpoint to send requests to. Usually in the format https://your-matomo-domain.tld/matomo.php. Must not be null

    • MatomoTracker

      @Deprecated public MatomoTracker(@NonNull @NonNull String hostUrl, int timeout)
      Deprecated.
      Please use MatomoTracker(TrackerConfiguration)
      Creates a tracker that will send MatomoRequests to the specified Tracking HTTP API endpoint.
      Parameters:
      hostUrl - url endpoint to send requests to. Usually in the format https://your-matomo-domain.tld/matomo.php.
      timeout - the timeout of the sent request in milliseconds or -1 if not set

    • MatomoTracker

      @Deprecated public MatomoTracker(@NonNull @NonNull String hostUrl, @Nullable String proxyHost, int proxyPort, int timeout)
      Deprecated.
      Please use MatomoTracker(TrackerConfiguration)
      Creates a tracker that will send MatomoRequests to the specified Tracking HTTP API endpoint.
      Parameters:
      hostUrl - url endpoint to send requests to. Usually in the format https://your-matomo-domain.tld/matomo.php.
      proxyHost - The hostname or IP address of an optional HTTP proxy, null allowed
      proxyPort - The port of an HTTP proxy or -1 if not set
      timeout - the timeout of the request in milliseconds or -1 if not set

    • MatomoTracker

      public MatomoTracker(@NonNull @NonNull TrackerConfiguration trackerConfiguration)
      Creates a new Matomo Tracker instance.
      Parameters:
      trackerConfiguration - Configurations parameters (you can use a builder)

    • MatomoTracker

      @Deprecated public MatomoTracker(@NonNull @NonNull String hostUrl, @Nullable String proxyHost, int proxyPort)
      Deprecated.
      Please use MatomoTracker(TrackerConfiguration)
      Creates a tracker that will send MatomoRequests to the specified Tracking HTTP API endpoint via the provided proxy.
      Parameters:
      hostUrl - url endpoint to send requests to. Usually in the format https://your-matomo-domain.tld/matomo.php.
      proxyHost - url endpoint for the proxy, null allowed
      proxyPort - proxy server port number or -1 if not set

  • Method Details

    • sendRequest

      public void sendRequest(@NonNull @NonNull MatomoRequest request)
      Sends a tracking request to Matomo using the HTTP GET method.

      Use this method if you want to send a single request. If you want to send multiple requests at once, use sendBulkRequest(Iterable) instead. If you want to send multiple requests asynchronously, use sendRequestAsync(MatomoRequest) or sendBulkRequestAsync(Iterable) instead.

      Parameters:
      request - request to send. must not be null

    • sendRequestAsync

      public CompletableFuture<MatomoRequest> sendRequestAsync(@NonNull @NonNull MatomoRequest request)
      Send a request asynchronously via HTTP GET.

      Use this method if you want to send a single request. If you want to send multiple requests at once, use sendBulkRequestAsync(Iterable) instead. If you want to send multiple requests synchronously, use sendRequest(MatomoRequest) or sendBulkRequest(Iterable) instead.

      Parameters:
      request - request to send
      Returns:
      completable future to let you know when the request is done. Contains the request.

    • sendRequestAsync

      @Deprecated public <T> CompletableFuture<T> sendRequestAsync(@NonNull @NonNull MatomoRequest request, @NonNull @NonNull Function<MatomoRequest,T> callback)
      Deprecated.
      Please use sendRequestAsync(MatomoRequest) in combination with CompletableFuture.thenAccept(Consumer) instead
      Send a request asynchronously via HTTP GET and specify a callback that gets executed when the response arrives.

      Use this method if you want to send a single request. If you want to send multiple requests at once, use sendBulkRequestAsync(Iterable, Consumer) instead. If you want to send multiple requests synchronously, use sendRequest(MatomoRequest) or sendBulkRequest(Iterable) instead.

      Parameters:
      request - request to send
      callback - callback that gets executed when response arrives, must not be null
      Returns:
      a completable future to let you know when the request is done. The future contains the callback result.

    • sendBulkRequest

      public void sendBulkRequest(MatomoRequest... requests)
      Send multiple requests in a single HTTP POST call.

      More efficient than sending several individual requests. If you want to send a single request, use sendRequest(MatomoRequest) instead. If you want to send multiple requests asynchronously, use sendBulkRequestAsync(Iterable) instead.

      Parameters:
      requests - the requests to send

    • sendBulkRequest

      public void sendBulkRequest(@NonNull @NonNull Iterable<? extends MatomoRequest> requests)
      Send multiple requests in a single HTTP POST call.

      More efficient than sending several individual requests. If you want to send a single request, use sendRequest(MatomoRequest) instead. If you want to send multiple requests asynchronously, use sendBulkRequestAsync(Iterable) instead.

      Parameters:
      requests - the requests to send

    • sendBulkRequest

      @Deprecated public void sendBulkRequest(@NonNull @NonNull Iterable<? extends MatomoRequest> requests, @Nullable String authToken)
      Deprecated.
      use sendBulkRequest(Iterable) instead and set the auth token in the tracker configuration or the requests directly.
      Send multiple requests in a single HTTP POST call. More efficient than sending several individual requests.

      Specify the AuthToken if parameters that require an auth token is used. If you want to send a single request, use sendRequest(MatomoRequest) instead. If you want to send multiple requests asynchronously, use sendBulkRequestAsync(Iterable) instead.

      Parameters:
      requests - the requests to send
      authToken - specify if any of the parameters use require AuthToken, if null the default auth token from the request or the tracker configuration is used.

    • sendBulkRequestAsync

      public CompletableFuture<Void> sendBulkRequestAsync(MatomoRequest... requests)
      Send multiple requests in a single HTTP call. More efficient than sending several individual requests.
      Parameters:
      requests - the requests to send
      Returns:
      completable future to let you know when the request is done

    • sendBulkRequestAsync

      public CompletableFuture<Void> sendBulkRequestAsync(@NonNull @NonNull Iterable<? extends MatomoRequest> requests)
      Send multiple requests in a single HTTP call. More efficient than sending several individual requests.
      Parameters:
      requests - the requests to send
      Returns:
      completable future to let you know when the request is done

    • sendBulkRequestAsync

      @Deprecated public CompletableFuture<Void> sendBulkRequestAsync(@NonNull @NonNull Iterable<? extends MatomoRequest> requests, @Nullable String authToken, @Nullable Consumer<Void> callback)
      Deprecated.
      Please set the auth token in the tracker configuration or the requests directly and use CompletableFuture.thenAccept(Consumer) instead for the callback.
      Send multiple requests in a single HTTP call. More efficient than sending several individual requests. Specify the AuthToken if parameters that require an auth token is used.
      Parameters:
      requests - the requests to send
      authToken - specify if any of the parameters use require AuthToken, if null the default auth token from the request or the tracker configuration is used
      callback - callback that gets executed when response arrives, null allowed
      Returns:
      a completable future to let you know when the request is done

    • sendBulkRequestAsync

      public CompletableFuture<Void> sendBulkRequestAsync(@NonNull @NonNull Iterable<? extends MatomoRequest> requests, @Nullable Consumer<Void> callback)
      Send multiple requests in a single HTTP call. More efficient than sending several individual requests.
      Parameters:
      requests - the requests to send
      callback - callback that gets executed when response arrives, null allowed
      Returns:
      completable future to let you know when the request is done

    • sendBulkRequestAsync

      public CompletableFuture<Void> sendBulkRequestAsync(@NonNull @NonNull Iterable<? extends MatomoRequest> requests, @Nullable String authToken)
      Deprecated.
      Please set the auth token in the tracker configuration or the requests directly and use sendBulkRequestAsync(Iterable) instead.
      Send multiple requests in a single HTTP call. More efficient than sending several individual requests. Specify the AuthToken if parameters that require an auth token is used.
      Parameters:
      requests - the requests to send
      authToken - specify if any of the parameters use require AuthToken, null allowed
      Returns:
      completable future to let you know when the request is done

    • setSenderFactory

      protected void setSenderFactory(SenderFactory senderFactory)