Package org.matomo.java.tracking

Class MatomoRequests

java.lang.Object
org.matomo.java.tracking.MatomoRequests
public class MatomoRequests extends Object
This class contains static methods for common tracking items to create MatomoRequest objects.

The intention of this class is to bundle common tracking items in a single place to make tracking easier. The methods contain the typical parameters for the tracking item and return a MatomoRequest.MatomoRequestBuilder object to add additional parameters, like the visitor ID, a user ID or custom dimensions.

  • Constructor Details

    • MatomoRequests

      public MatomoRequests()

  • Method Details

    • action

      @NonNull public static MatomoRequest.MatomoRequestBuilder action(@NonNull @NonNull String url, @NonNull @NonNull ActionType type)
      Creates a MatomoRequest object for a download or a link action.
      Parameters:
      url - The URL of the download or link. Must not be null.
      type - The type of the action. Either ActionType.DOWNLOAD or ActionType.LINK.
      Returns:
      A MatomoRequest.MatomoRequestBuilder object to add additional parameters.

    • contentImpression

      @NonNull public static MatomoRequest.MatomoRequestBuilder contentImpression(@NonNull @NonNull String name, @Nullable String piece, @Nullable String target)
      Creates a MatomoRequest object for a content impression.

      A content impression is a view of a content piece. The content piece can be a product, an article, a video, a banner, etc. The content piece can be specified by the parameters piece and target. The name parameter is required and should be a descriptive name of the content piece.

      Parameters:
      name - The name of the content piece, like the name of a product or an article. Must not be null. Example: "SuperPhone".
      piece - The content piece. Can be null. Example: "Smartphone".
      target - The target of the content piece, like the URL of a product or an article. Can be null. Example: "https://example.com/superphone".
      Returns:
      A MatomoRequest.MatomoRequestBuilder object to add additional parameters.

    • contentInteraction

      @NonNull public static MatomoRequest.MatomoRequestBuilder contentInteraction(@NonNull @NonNull String interaction, @NonNull @NonNull String name, @Nullable String piece, @Nullable String target)
      Creates a MatomoRequest object for a content interaction.

      Make sure you have tracked a content impression using the same content name and content piece, otherwise it will not count.

      A content interaction is an interaction with a content piece. The content piece can be a product, an article, a video, a banner, etc. The content piece can be specified by the parameters piece and target. The name parameter is required and should be a descriptive name of the content piece. The interaction parameter is required and should be the type of the interaction, like "click" or "add-to-cart".

      Parameters:
      interaction - The type of the interaction. Must not be null. Example: "click".
      name - The name of the content piece, like the name of a product or an article.
      piece - The content piece. Can be null. Example: "Blog Article XYZ".
      target - The target of the content piece, like the URL of a product or an article. Can be null. Example: "https://example.com/blog/article-xyz".
      Returns:
      A MatomoRequest.MatomoRequestBuilder object to add additional parameters.

    • crash

      @NonNull public static MatomoRequest.MatomoRequestBuilder crash(@NonNull @NonNull String message, @Nullable String type, @Nullable String category, @Nullable String stackTrace, @Nullable String location, @Nullable Integer line, @Nullable Integer column)
      Creates a MatomoRequest object for a crash.

      Requires Crash Analytics plugin to be enabled in the target Matomo instance.

      A crash is an error that causes the application to stop working. The parameters message and stackTrace are required. The other parameters are optional. The type parameter can be used to specify the type of the crash, like NullPointerException. The category parameter can be used to specify the category of the crash, like payment failure. The location, line and column can be used to specify the location of the crash. The location parameter should be the name of the file where the crash occurred. The line and column parameters should be the line and column number of the crash.

      Parameters:
      message - The message of the crash. Must not be null.
      type - The type of the crash. Can be null. Example: java.lang.NullPointerException
      category - The category of the crash. Can be null. Example: "payment failure".
      stackTrace - The stack trace of the crash. Must not be null.
      location - The location of the crash. Can be null. Example: "MainActivity.java".
      line - The line number of the crash. Can be null. Example: 42.
      column - The column number of the crash. Can be null. Example: 23.
      Returns:
      A MatomoRequest.MatomoRequestBuilder object to add additional parameters.

    • crash

      @NonNull public static MatomoRequest.MatomoRequestBuilder crash(@NonNull @NonNull Throwable throwable, @Nullable String category)
      Creates a MatomoRequest object for a crash with information from a Throwable.

      Requires Crash Analytics plugin to be enabled in the target Matomo instance.

      The category parameter can be used to specify the category of the crash, like payment failure.

      Parameters:
      throwable - The throwable that caused the crash. Must not be null.
      category - The category of the crash. Can be null. Example: "payment failure".
      Returns:
      A MatomoRequest.MatomoRequestBuilder object to add additional parameters.

    • ecommerceCartUpdate

      @NonNull public static MatomoRequest.MatomoRequestBuilder ecommerceCartUpdate(@NonNull @NonNull Double revenue)
      Creates a MatomoRequest object for a ecommerce cart update (add item, remove item, update item).

      The revenue parameter is required and should be the total revenue of the cart.

      Parameters:
      revenue - The total revenue of the cart. Must not be null.
      Returns:
      A MatomoRequest.MatomoRequestBuilder object to add additional parameters.

    • ecommerceOrder

      @NonNull public static MatomoRequest.MatomoRequestBuilder ecommerceOrder(@NonNull @NonNull String id, @NonNull @NonNull Double revenue, @Nullable Double subtotal, @Nullable Double tax, @Nullable Double shippingCost, @Nullable Double discount)
      Creates a MatomoRequest object for a ecommerce order.

      All revenues (revenue, subtotal, tax, shippingCost, discount) will be individually summed and reported in Matomo reports.

      The id and revenue parameters are required and should be the order ID and the total revenue of the order. The other parameters are optional. The subtotal, tax, shippingCost and discount parameters should be the subtotal, tax, shipping cost and discount of the order.

      If the Ecommerce order contains items (products), you must call MatomoRequest.MatomoRequestBuilder.ecommerceItems(EcommerceItems) to add the items to the request.

      Parameters:
      id - An order ID. Can be a stock keeping unit (SKU) or a unique ID. Must not be null.
      revenue - The total revenue of the order. Must not be null.
      subtotal - The subtotal of the order. Can be null.
      tax - The tax of the order. Can be null.
      shippingCost - The shipping cost of the order. Can be null.
      discount - The discount of the order. Can be null.
      Returns:
      A MatomoRequest.MatomoRequestBuilder object to add additional parameters.

    • event

      @NonNull public static MatomoRequest.MatomoRequestBuilder event(@NonNull @NonNull String category, @NonNull @NonNull String action, @Nullable String name, @Nullable Double value)
      Creates a MatomoRequest object for an event.

      The category and action parameters are required and should be the category and action of the event. The name and value parameters are optional. The category parameter should be a category of the event, like "Travel". The action parameter should be an action of the event, like "Book flight". The name parameter should be the name of the event, like "Flight to Berlin". The value parameter should be the value of the event, like the price of the flight.

      Parameters:
      category - The category of the event. Must not be null. Example: "Music"
      action - The action of the event. Must not be null. Example: "Play"
      name - The name of the event. Can be null. Example: "Edvard Grieg - The Death of Ase"
      value - The value of the event. Can be null. Example: 9.99
      Returns:
      A MatomoRequest.MatomoRequestBuilder object to add additional parameters.

    • goal

      @NonNull public static MatomoRequest.MatomoRequestBuilder goal(int id, @Nullable Double revenue)
      Creates a MatomoRequest object for a conversion of a goal of the website.

      The id parameter is required and should be the ID of the goal. The revenue, name and value parameters are optional. The revenue parameter should be the revenue of the conversion. The name parameter should be the name of the conversion. The value parameter should be the value of the conversion.

      Parameters:
      id - The ID of the goal. Must not be null. Example: 1
      revenue - The revenue of the conversion. Can be null. Example: 9.99
      Returns:
      A MatomoRequest.MatomoRequestBuilder object to add additional parameters.

    • pageView

      @NonNull public static MatomoRequest.MatomoRequestBuilder pageView(@NonNull @NonNull String name)
      Creates a MatomoRequest object for a page view.

      The name parameter is required and should be the name of the page.

      Parameters:
      name - The name of the page. Must not be null. Example: "Home"
      Returns:
      A MatomoRequest.MatomoRequestBuilder object to add additional parameters.

    • siteSearch

      @NonNull public static MatomoRequest.MatomoRequestBuilder siteSearch(@NonNull @NonNull String query, @Nullable String category, @Nullable Long resultsCount)
      Creates a MatomoRequest object for a search.

      These are used to populate reports in Actions > Site Search.

      The query parameter is required and should be the search query. The category and resultsCount parameters are optional. The category parameter should be the category of the search, like "Music". The resultsCount parameter should be the number of results of the search.

      Parameters:
      query - The search query. Must not be null. Example: "Edvard Grieg"
      category - The category of the search. Can be null. Example: "Music"
      resultsCount - The number of results of the search. Can be null. Example: 42
      Returns:
      A MatomoRequest.MatomoRequestBuilder object to add additional parameters.

    • ping

      @NonNull public static MatomoRequest.MatomoRequestBuilder ping()
      Creates a MatomoRequest object for a ping.

      Ping requests do not track new actions. If they are sent within the standard visit length (see global.ini.php), they will extend the existing visit and the current last action for the visit. If after the standard visit length, ping requests will create a new visit using the last action in the last known visit.

      Returns:
      A MatomoRequest.MatomoRequestBuilder object to add additional parameters.