Added possibility to set custom tracking parameters for 3rd party plu…

…gins

Eg needed for Custom Dimensions plugin  ( matomo-org/matomo#9129 )

PiwikTracker.php

@@ -89,6 +89,7 @@ function __construct($idSite, $apiUrl = '')
         $this->forcedNewVisit = false;
         $this->generationTime = false;
         $this->pageCustomVar = false;
+        $this->customParameters = array();
         $this->customData = false;
         $this->hasCookies = false;
         $this->token_auth = false;
@@ -304,6 +305,27 @@ public function clearCustomVariables()
         $this->eventCustomVar = array();
     }
 
+    /**
+     * Sets a custom tracking paramater. This is useful if you need to send any tracking parameters for a 3rd party
+     * plugin that is not shipped with Piwik itself. Please note that custom parameters are cleared after each
+     * tracking request.
+     *
+     * @param string $trackingApiParameter The name of the tracking API parameter, eg 'dimension1'
+     * @param string $value Custom variable value  The value that shall be sent for this tracking parameter.
+     * @throws Exception
+     */
+    public function setCustomTrackingParameter($trackingApiParameter, $value)
+    {
+        $this->customParameters[$trackingApiParameter] = $value;
+    }
+
+    /**
+     * Clear / reset all previously set custom tracking parameters.
+     */
+    public function clearCustomTrackingParameter()
+    {
+        $this->customParameters = array();
+    }
 
     /**
      * Sets the current visitor ID to a random new one.
@@ -1328,6 +1350,7 @@ protected function sendRequest($url, $method = 'GET', $data = null, $force = fal
 
             // Clear custom variables so they don't get copied over to other users in the bulk request
             $this->clearCustomVariables();
+            $this->clearCustomTrackingParameter();
             $this->userAgent = false;
             $this->acceptLanguage = false;
             return true;
@@ -1426,6 +1449,13 @@ protected function getRequest($idSite)
     {
         $this->setFirstPartyCookies();
 
+        $customFields = '';
+        if (!empty($this->customParameters)) {
+            foreach ($this->customParameters as $parameter => $value) {
+                $customFields .= '&' . urlencode($parameter) . '=' . urlencode($value);
+            }
+        }
+
         $url = $this->getBaseUrl() .
             '?idsite=' . $idSite .
             '&rec=1' .
@@ -1484,15 +1514,16 @@ protected function getRequest($idSite)
             (!empty($this->city) ? '&city=' . urlencode($this->city) : '') .
             (!empty($this->lat) ? '&lat=' . urlencode($this->lat) : '') .
             (!empty($this->long) ? '&long=' . urlencode($this->long) : '') .
+            $customFields .
             (!$this->sendImageResponse ? '&send_image=0' : '') .
 
             // DEBUG
             $this->DEBUG_APPEND_URL;
 
-
         // Reset page level custom variables after this page view
         $this->pageCustomVar = array();
         $this->eventCustomVar = array();
+        $this->clearCustomTrackingParameter();
 
         // force new visit only once, user must call again setForceNewVisit()
         $this->forcedNewVisit = false;
@@ -1711,4 +1742,3 @@ function Piwik_getUrlTrackGoal($idSite, $idGoal, $revenue = 0.0)
     $tracker = new PiwikTracker($idSite);
     return $tracker->getUrlTrackGoal($idGoal, $revenue);
 }
-