diff --git a/core/Tracker/Action.php b/core/Tracker/Action.php
index 1017798312bba1ef92dbbd393cd07ac497de86c5..a5a5553e94c95df4f90c9e7a1fee875fbfbd1550 100644
--- a/core/Tracker/Action.php
+++ b/core/Tracker/Action.php
@@ -639,10 +639,11 @@ class Action implements ActionInterface
);
Common::printDebug($insertWithoutNulls);
- /*
- * send the Action object ($this) and the list of ids ($info) as arguments to the event
- */
- Piwik_PostEvent('Tracker.recordAction', array($this, $info));
+ /**
+ * This hook is called after saving (and updating) visitor information. You can use for instance to sync the
+ * recorded action with third party systems.
+ */
+ Piwik_PostEvent('Tracker.recordAction', array($trackerAction = $this, $info));
}
public function getCustomVariables()
diff --git a/core/Tracker/Cache.php b/core/Tracker/Cache.php
index 8ae471f54f513c68549a08c6ab79131e5ede7211..5d7827e44291c679e2ddee633e7e786ae212be47 100644
--- a/core/Tracker/Cache.php
+++ b/core/Tracker/Cache.php
@@ -61,6 +61,10 @@ class Cache
Piwik::setUserIsSuperUser();
$content = array();
+ /**
+ * This hook is called to get the details of a specific site depending on the id. You can use this to add any
+ * custom attributes to the website.
+ */
Piwik_PostEvent('Site.getSiteAttributes', array(&$content, $idSite));
// restore original user privilege
@@ -104,6 +108,11 @@ class Cache
'isBrowserTriggerEnabled' => Rules::isBrowserTriggerEnabled(),
'lastTrackerCronRun' => Piwik_GetOption('lastTrackerCronRun'),
);
+
+ /**
+ * This event is triggered to add any custom content to the Tracker cache. You may want to cache any tracker
+ * data that is expensive to re-calculate on each tracking request.
+ */
Piwik_PostEvent('Tracker.setTrackerCacheGeneral', array(&$cacheContent));
self::setCacheGeneral($cacheContent);
return $cacheContent;
diff --git a/core/Tracker/GoalManager.php b/core/Tracker/GoalManager.php
index 16b0cba03c7fcaf6ed5dafdfe35592a78f97a241..be7255d199a56b0bb8fe53950e964c3d9b5ca33d 100644
--- a/core/Tracker/GoalManager.php
+++ b/core/Tracker/GoalManager.php
@@ -405,6 +405,10 @@ class GoalManager
$this->recordEcommerceItems($goal, $items);
}
+ /**
+ * This hook is called after recording an ecommerce goal. You can use for instance to sync the recorded goal
+ * with third party systems. `$goal` contains all available information like `items` and `revenue`.
+ */
Piwik_PostEvent('Tracker.recordEcommerceGoal', array($goal));
}
@@ -766,6 +770,10 @@ class GoalManager
$this->recordGoal($newGoal);
+ /**
+ * This hook is called after recording a standard goal. You can use for instance to sync the recorded goal
+ * with third party systems. `$goal` contains all available information like `url` and `revenue`.
+ */
Piwik_PostEvent('Tracker.recordStandardGoals', array($newGoal));
}
}
diff --git a/core/Tracker/Referrer.php b/core/Tracker/Referrer.php
index d4088d99c93f956cbe65ad4f52d48286e0e58440..5954ca1dc81e8c9b93fe271a138880d13cbeb6de 100644
--- a/core/Tracker/Referrer.php
+++ b/core/Tracker/Referrer.php
@@ -127,6 +127,11 @@ class Referrer
protected function detectReferrerSearchEngine()
{
$searchEngineInformation = UrlHelper::extractSearchEngineInformationFromUrl($this->referrerUrl);
+
+ /**
+ * This event is triggered after basic search engine detection has been attempted. A plugin can use this event
+ * to modify or provide new results based on the passed referrer URL.
+ */
Piwik_PostEvent('Tracker.detectReferrerSearchEngine', array(&$searchEngineInformation, $this->referrerUrl));
if ($searchEngineInformation === false) {
return false;
diff --git a/core/Tracker/Request.php b/core/Tracker/Request.php
index 844254e59338bb30eccee738937f1906c3e9cf8e..92350dbe7d9770d16106c85f3abec280512a753b 100644
--- a/core/Tracker/Request.php
+++ b/core/Tracker/Request.php
@@ -291,6 +291,12 @@ class Request
public function getIdSite()
{
$idSite = Common::getRequestVar('idsite', 0, 'int', $this->params);
+
+ /**
+ * This event allows a plugin to set/change the idsite in the tracking request. Note: A modified idSite has to
+ * be higher than 0, otherwise an exception will be triggered. By default the idSite is specified on the URL
+ * parameter `idsite`.
+ */
Piwik_PostEvent('Tracker.setSiteId', array(&$idSite, $this->params));
if ($idSite <= 0) {
throw new Exception('Invalid idSite');
diff --git a/core/Tracker/Visit.php b/core/Tracker/Visit.php
index 99f2c8176405cb81f22114f6c8e378c71826c75b..4f45fdf1374d7059cbe515ec1d6acb3e7cf207e1 100644
--- a/core/Tracker/Visit.php
+++ b/core/Tracker/Visit.php
@@ -92,7 +92,9 @@ class Visit implements VisitInterface
return;
}
- // Anonymize IP (after testing for IP exclusion)
+ /**
+ * This event can be used for instance to anonymize the IP (after testing for IP exclusion).
+ */
Piwik_PostEvent('Tracker.setVisitorIp', array(&$this->visitorInfo['location_ip']));
$this->visitorCustomVariables = $this->request->getCustomVariables($scope = 'visit');
@@ -303,7 +305,10 @@ class Visit implements VisitInterface
// Custom Variables overwrite previous values on each page view
$valuesToUpdate = array_merge($valuesToUpdate, $this->visitorCustomVariables);
- // trigger event before update
+ /**
+ * This event is triggered before a known visitor is updated. Use it to change any visitor information before
+ * the visitor is saved.
+ */
Piwik_PostEvent('Tracker.knownVisitorUpdate', array(&$valuesToUpdate));
$this->visitorInfo['time_spent_ref_action'] = $this->getTimeSpentReferrerAction();
@@ -345,6 +350,10 @@ class Visit implements VisitInterface
. " wasn't found in the DB, we fallback to a new visitor");
}
+ /**
+ * After a known visitor is updated by Piwik, this event is called. Useful for plugins that want to register
+ * information about a returning visitor, or filter the existing information.
+ */
Piwik_PostEvent('Tracker.knownVisitorInformation', array(&$this->visitorInfo));
}
@@ -461,6 +470,12 @@ class Visit implements VisitInterface
$extraInfo = array(
'UserAgent' => $this->request->getUserAgent(),
);
+
+ /**
+ * Before a new visitor is updated by Piwik, this event is called. Useful for plugins that want to register
+ * new information about a visitor, or filter the existing information. `$extraInfo` contains the UserAgent.
+ * You can for instance change the user's location country depending on the User Agent.
+ */
Piwik_PostEvent('Tracker.newVisitorInformation', array(&$this->visitorInfo, $extraInfo));
$this->request->overrideLocation($this->visitorInfo);
@@ -492,8 +507,6 @@ class Visit implements VisitInterface
*/
protected function saveVisitorInformation()
{
- Piwik_PostEvent('Tracker.visitorInformation', array(&$this->visitorInfo));
-
$this->visitorInfo['location_browser_lang'] = substr($this->visitorInfo['location_browser_lang'], 0, 20);
$this->visitorInfo['referer_name'] = substr($this->visitorInfo['referer_name'], 0, 70);
$this->visitorInfo['referer_keyword'] = substr($this->visitorInfo['referer_keyword'], 0, 255);
diff --git a/core/Tracker/VisitExcluded.php b/core/Tracker/VisitExcluded.php
index bba1d5c483be4a644d69f30943a1d2276d3b1240..bcb5595732d2de61264a3d705fa3a13849d3b98e 100644
--- a/core/Tracker/VisitExcluded.php
+++ b/core/Tracker/VisitExcluded.php
@@ -71,7 +71,10 @@ class VisitExcluded
}
}
- /* custom filters can override the built-in filters above */
+ /**
+ * At every page view, this event will be called. It is useful for plugins that want to exclude specific visits
+ * (ie. IP excluding, Cookie excluding). If you set `$excluded` to `true`, the visit will be excluded.
+ */
Piwik_PostEvent('Tracker.isExcludedVisit', array(&$excluded));
/*