Set idgoal to 0 on ecommerce parameters (#162)

Author: dheid

core/src/main/java/org/matomo/java/tracking/MatomoRequest.java

@@ -41,7 +41,7 @@
 
 /**
  * A class that implements the <a href="https://developer.matomo.org/api-reference/tracking-api">
- * Matomo Tracking HTTP API</a>.  These requests can be sent using {@link MatomoTracker}.
+ * Matomo Tracking HTTP API</a>. These requests can be sent using {@link MatomoTracker}.
  *
  * @author brettcsorba
  */
@@ -55,17 +55,20 @@ public class MatomoRequest {
 
   /**
    * The ID of the website we're tracking a visit/action for. Only needed, if no default site id is
-   * configured
+   * configured.
    */
   @TrackingParameter(name = "rec")
   @Default
   private Boolean required = true;
 
   /**
    * The ID of the website we're tracking a visit/action for. Only needed, if no default site id is
-   * configured
+   * configured.
    */
-  @TrackingParameter(name = "idsite")
+  @TrackingParameter(
+      name = "idsite",
+      min = 1
+  )
   private Integer siteId;
 
   /**
@@ -130,7 +133,7 @@ public class MatomoRequest {
    * database). Then you would manually increment the counts by one on each new visit or "session",
    * depending on how you choose to define a visit.
    */
-  @TrackingParameter(name = "_idvc")
+  @TrackingParameter(name = "_idvc", min = 0)
   private Integer visitorVisitCount;
 
   /**
@@ -156,9 +159,9 @@ public class MatomoRequest {
   /**
    * The campaign keyword (see
    * <a href="https://matomo.org/docs/tracking-campaigns/">Tracking Campaigns</a>). Used to
-   * populate
-   * the <em>Referrers &gt; Campaigns</em> report (clicking on a campaign loads all keywords for
-   * this campaign). This parameter will only be used for the first pageview of a visit.
+   * populate the <em>Referrers &gt; Campaigns</em> report (clicking on a campaign loads all
+   * keywords for this campaign). This parameter will only be used for the first pageview of a
+   * visit.
    */
   @TrackingParameter(name = "_rck")
   private String campaignKeyword;
@@ -172,19 +175,31 @@ public class MatomoRequest {
   /**
    * The current hour (local time).
    */
-  @TrackingParameter(name = "h")
+  @TrackingParameter(
+      name = "h",
+      min = 0,
+      max = 23
+  )
   private Integer currentHour;
 
   /**
    * The current minute (local time).
    */
-  @TrackingParameter(name = "m")
+  @TrackingParameter(
+      name = "m",
+      min = 0,
+      max = 59
+  )
   private Integer currentMinute;
 
   /**
    * The current second (local time).
    */
-  @TrackingParameter(name = "s")
+  @TrackingParameter(
+      name = "s",
+      min = 0,
+      max = 59
+  )
   private Integer currentSecond;
 
   /**
@@ -321,7 +336,10 @@ public class MatomoRequest {
    * results displayed on the results page. When keywords are tracked with &search_count=0 they will
    * appear in the "No Result Search Keyword" report.
    */
-  @TrackingParameter(name = "search_count")
+  @TrackingParameter(
+      name = "search_count",
+      min = 0
+  )
   private Long searchResultsCount;
 
   /**
@@ -335,9 +353,9 @@ public class MatomoRequest {
 
   /**
    * If specified, the tracking request will trigger a conversion for the goal of the website being
-   * tracked with this ID.
+   * tracked with this ID. The value 0 tracks an ecommerce interaction.
    */
-  @TrackingParameter(name = "idgoal")
+  @TrackingParameter(name = "idgoal", min = 0)
   private Integer goalId;
 
   /**
@@ -365,39 +383,39 @@ public class MatomoRequest {
   /**
    * How long it took to connect to server.
    */
-  @TrackingParameter(name = "pf_net")
+  @TrackingParameter(name = "pf_net", min = 0)
   private Long networkTime;
 
   /**
    * How long it took the server to generate page.
    */
-  @TrackingParameter(name = "pf_srv")
+  @TrackingParameter(name = "pf_srv", min = 0)
   private Long serverTime;
 
   /**
    * How long it takes the browser to download the response from the server.
    */
-  @TrackingParameter(name = "pf_tfr")
+  @TrackingParameter(name = "pf_tfr", min = 0)
   private Long transferTime;
 
   /**
    * How long the browser spends loading the webpage after the response was fully received until the
    * user can start interacting with it.
    */
-  @TrackingParameter(name = "pf_dm1")
+  @TrackingParameter(name = "pf_dm1", min = 0)
   private Long domProcessingTime;
 
   /**
    * How long it takes for the browser to load media and execute any Javascript code listening for
    * the DOMContentLoaded event.
    */
-  @TrackingParameter(name = "pf_dm2")
+  @TrackingParameter(name = "pf_dm2", min = 0)
   private Long domCompletionTime;
 
   /**
    * How long it takes the browser to execute Javascript code waiting for the window.load event.
    */
-  @TrackingParameter(name = "pf_onl")
+  @TrackingParameter(name = "pf_onl", min = 0)
   private Long onloadTime;
 
   /**
@@ -450,8 +468,7 @@ public class MatomoRequest {
 
   /**
    * The unique string identifier for the ecommerce order (required when tracking an ecommerce
-   * order). you must set &idgoal=0 in the request to track an ecommerce interaction: cart update or
-   * an ecommerce order.
+   * order).
    */
   @TrackingParameter(name = "ec_id")
   private String ecommerceId;
@@ -546,13 +563,13 @@ public class MatomoRequest {
   /**
    * An override value for the visitor's latitude, eg 22.456.
    */
-  @TrackingParameter(name = "lat")
+  @TrackingParameter(name = "lat", min = -90, max = 90)
   private Double visitorLatitude;
 
   /**
    * An override value for the visitor's longitude, eg 22.456.
    */
-  @TrackingParameter(name = "long")
+  @TrackingParameter(name = "long", min = -180, max = 180)
   private Double visitorLongitude;
 
   /**
@@ -670,23 +687,22 @@ public class MatomoRequest {
    *
    * <p>Optional for crash analytics
    */
-  @TrackingParameter(name = "cra_rl")
+  @TrackingParameter(name = "cra_rl", min = 0)
   private Integer crashLine;
 
   /**
    * The column within the line where the crash occurred.
    *
    * <p>Optional for crash analytics
    */
-  @TrackingParameter(name = "cra_rc")
+  @TrackingParameter(name = "cra_rc", min = 0)
   private Integer crashColumn;
 
   /**
    * The Matomo session ID sent as a cookie {@code MATOMO_SESSID}.
    *
    * <p>If not null a cookie with the name {@code MATOMO_SESSID} will be sent with the value of
-   * this
-   * parameter.
+   * this parameter.
    */
   private String sessionId;
 

core/src/main/java/org/matomo/java/tracking/MatomoTracker.java

@@ -142,7 +142,7 @@ public MatomoTracker(
   public void sendRequest(@NonNull MatomoRequest request) {
     if (trackerConfiguration.isEnabled()) {
       log.debug("Sending request via GET: {}", request);
-      validate(request);
+      applyGoalIdAndCheckSiteId(request);
       initializeSender();
       sender.sendSingle(request);
     } else {
@@ -192,7 +192,7 @@ public <T> CompletableFuture<T> sendRequestAsync(
       @NonNull Function<MatomoRequest, T> callback
   ) {
     if (trackerConfiguration.isEnabled()) {
-      validate(request);
+      applyGoalIdAndCheckSiteId(request);
       log.debug("Sending async request via GET: {}", request);
       initializeSender();
       CompletableFuture<MatomoRequest> future = sender.sendSingleAsync(request);
@@ -202,9 +202,17 @@ public <T> CompletableFuture<T> sendRequestAsync(
     return CompletableFuture.completedFuture(null);
   }
 
-  private void validate(
+  private void applyGoalIdAndCheckSiteId(
       @NonNull MatomoRequest request
   ) {
+    if (request.getGoalId() == null && (
+        request.getEcommerceId() != null || request.getEcommerceRevenue() != null
+            || request.getEcommerceDiscount() != null || request.getEcommerceItems() != null
+            || request.getEcommerceLastOrderTimestamp() != null
+            || request.getEcommerceShippingCost() != null || request.getEcommerceSubtotal() != null
+            || request.getEcommerceTax() != null)) {
+      request.setGoalId(0);
+    }
     if (trackerConfiguration.getDefaultSiteId() == null && request.getSiteId() == null) {
       throw new IllegalArgumentException("No default site ID and no request site ID is given");
     }
@@ -256,7 +264,7 @@ public void sendBulkRequest(
   ) {
     if (trackerConfiguration.isEnabled()) {
       for (MatomoRequest request : requests) {
-        validate(request);
+        applyGoalIdAndCheckSiteId(request);
       }
       log.debug("Sending requests via POST: {}", requests);
       initializeSender();
@@ -311,7 +319,7 @@ public CompletableFuture<Void> sendBulkRequestAsync(
   ) {
     if (trackerConfiguration.isEnabled()) {
       for (MatomoRequest request : requests) {
-        validate(request);
+        applyGoalIdAndCheckSiteId(request);
       }
       log.debug("Sending async requests via POST: {}", requests);
       initializeSender();

core/src/main/java/org/matomo/java/tracking/QueryCreator.java

@@ -28,7 +28,8 @@
 @RequiredArgsConstructor
 class QueryCreator {
 
-  private static final TrackingParameterMethod[] TRACKING_PARAMETER_METHODS = initializeTrackingParameterMethods();
+  private static final TrackingParameterMethod[] TRACKING_PARAMETER_METHODS =
+      initializeTrackingParameterMethods();
 
   private final TrackerConfiguration trackerConfiguration;
 
@@ -44,15 +45,20 @@ private static TrackingParameterMethod[] initializeTrackingParameterMethods() {
   }
 
   private static void addMethods(
-      Collection<TrackingParameterMethod> methods, Member member, TrackingParameter trackingParameter
+      Collection<TrackingParameterMethod> methods,
+      Member member,
+      TrackingParameter trackingParameter
   ) {
     try {
-      for (PropertyDescriptor pd : Introspector.getBeanInfo(MatomoRequest.class).getPropertyDescriptors()) {
+      for (PropertyDescriptor pd : Introspector.getBeanInfo(MatomoRequest.class)
+                                               .getPropertyDescriptors()) {
         if (member.getName().equals(pd.getName())) {
           String regex = trackingParameter.regex();
           methods.add(TrackingParameterMethod
               .builder()
               .parameterName(trackingParameter.name())
+              .min(trackingParameter.min())
+              .max(trackingParameter.max())
               .maxLength(trackingParameter.maxLength())
               .method(pd.getReadMethod())
               .pattern(regex == null || regex.isEmpty() || regex.trim().isEmpty() ? null :
@@ -97,7 +103,10 @@ String createQuery(
       for (Entry<Long, Object> entry : request.getDimensions().entrySet()) {
         if (entry.getKey() != null && entry.getValue() != null) {
           appendAmpersand(query);
-          query.append("dimension").append(entry.getKey()).append('=').append(encode(entry.getValue().toString()));
+          query.append("dimension")
+               .append(entry.getKey())
+               .append('=')
+               .append(encode(entry.getValue().toString()));
         }
       }
     }

core/src/main/java/org/matomo/java/tracking/RequestValidator.java

@@ -25,26 +25,16 @@ static void validate(
       @Nullable
       CharSequence authToken
   ) {
-    if (request.getSiteId() != null && request.getSiteId() < 0) {
-      throw new IllegalArgumentException("Site ID must not be negative");
-    }
-    if (request.getGoalId() == null && (
-        request.getEcommerceId() != null || request.getEcommerceRevenue() != null
-            || request.getEcommerceDiscount() != null || request.getEcommerceItems() != null
-            || request.getEcommerceLastOrderTimestamp() != null
-            || request.getEcommerceShippingCost() != null || request.getEcommerceSubtotal() != null
-            || request.getEcommerceTax() != null)) {
-      throw new MatomoException("Goal ID must be set if ecommerce parameters are used");
-    }
+
     if (request.getSearchResultsCount() != null && request.getSearchQuery() == null) {
       throw new MatomoException("Search query must be set if search results count is set");
     }
     if (authToken == null) {
       if (request.getVisitorLongitude() != null || request.getVisitorLatitude() != null
           || request.getVisitorRegion() != null || request.getVisitorCity() != null
-          || request.getVisitorCountry() != null) {
+          || request.getVisitorCountry() != null || request.getVisitorIp() != null) {
         throw new MatomoException(
-            "Auth token must be present if longitude, latitude, region, city or country are set");
+            "Auth token must be present if visitor longitude, latitude, region, city, country or IP are set");
       }
       if (request.getRequestTimestamp() != null && request
           .getRequestTimestamp()

core/src/main/java/org/matomo/java/tracking/TrackingParameter.java

@@ -20,6 +20,10 @@
 
   String regex() default "";
 
+  double min() default Double.MIN_VALUE;
+
+  double max() default Double.MAX_VALUE;
+
   int maxLength() default Integer.MAX_VALUE;
 
 }

core/src/main/java/org/matomo/java/tracking/TrackingParameterMethod.java

@@ -23,6 +23,10 @@ class TrackingParameterMethod {
 
   Pattern pattern;
 
+  double min;
+
+  double max;
+
   int maxLength;
 
   void validateParameterValue(@NonNull Object parameterValue) {
@@ -34,12 +38,30 @@ void validateParameterValue(@NonNull Object parameterValue) {
           pattern
       ));
     }
-    if (parameterValue.toString().length() > maxLength) {
+    if (maxLength != 0 && parameterValue.toString().length() > maxLength) {
       throw new MatomoException(String.format("Invalid value for %s. Must be less or equal than %d characters",
           parameterName,
           maxLength
       ));
     }
+    if (parameterValue instanceof Number) {
+      Number number = (Number) parameterValue;
+      if (number.doubleValue() < min) {
+        throw new MatomoException(String.format(
+            "Invalid value for %s. Must be greater or equal than %s",
+            parameterName,
+            min % 1 == 0 ? Long.toString((long) min) : min
+        ));
+
+      }
+      if (number.doubleValue() > max) {
+        throw new MatomoException(String.format(
+            "Invalid value for %s. Must be less or equal than %s",
+            parameterName,
+            max % 1 == 0 ? Long.toString((long) max) : max
+        ));
+      }
+    }
   }
 
 }