Merge pull request matomo-org#15 from piwik/customparameters

Added possibility to set any custom tracking parameters for 3rd party plugins

Author: Matthieu Aubry

PiwikTracker.php

@@ -89,6 +89,7 @@ public 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;
@@ -308,6 +309,28 @@ public function clearCustomVariables()
         $this->eventCustomVar = array();
     }
 
+    /**
+     * Sets a custom tracking parameter. 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 Tracking parameter 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 clearCustomTrackingParameters()
+    {
+        $this->customParameters = array();
+    }
+
     /**
      * Sets the current visitor ID to a random new one.
      */
@@ -1396,6 +1419,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->clearCustomTrackingParameters();
             $this->userAgent = false;
             $this->acceptLanguage = false;
 
@@ -1505,6 +1529,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' .
@@ -1568,6 +1599,7 @@ 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
@@ -1577,6 +1609,7 @@ protected function getRequest($idSite)
         // Reset page level custom variables after this page view
         $this->pageCustomVar = array();
         $this->eventCustomVar = array();
+        $this->clearCustomTrackingParameters();
 
         // force new visit only once, user must call again setForceNewVisit()
         $this->forcedNewVisit = false;
@@ -1811,4 +1844,4 @@ function Piwik_getUrlTrackGoal($idSite, $idGoal, $revenue = 0.0)
     $tracker = new PiwikTracker($idSite);
 
     return $tracker->getUrlTrackGoal($idGoal, $revenue);
-}
+}