From ec8a5f36e92fa9b7753af2f95439c6635b4b3b35 Mon Sep 17 00:00:00 2001 From: Thomas Steur Date: Sun, 14 Sep 2014 20:30:31 +0200 Subject: refs #4996 also display URL of media on hover next to the image. added some documentation --- js/piwik.js | 91 +++++++++++++++++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 83 insertions(+), 8 deletions(-) (limited to 'js') diff --git a/js/piwik.js b/js/piwik.js index 7312c7f8c3..60e2913769 100644 --- a/js/piwik.js +++ b/js/piwik.js @@ -4707,6 +4707,14 @@ if (typeof Piwik !== 'object') { } }, + /** + * Scans the entire DOM for all content blocks and tracks all impressions once the DOM ready event has + * been triggered. + * + * If you only want to track visible content impressions have a look at `trackVisibleContentImpressions()`. + * We do not track an impression of the same content block twice if you call this method multiple times + * unless `trackPageView()` is called meanwhile. This is useful for single page applications. + */ trackAllContentImpressions: function () { if (isOverlaySession(configTrackerSiteId)) { return; @@ -4723,6 +4731,40 @@ if (typeof Piwik !== 'object') { }); }, + /** + * Scans the entire DOM for all content blocks as soon as the page is loaded. It tracks an impression + * only if a content block is actually visible. Meaning it is not hidden and the content is or was at + * some point in the viewport. + * + * If you want to track all content blocks have a look at `trackAllContentImpressions()`. + * We do not track an impression of the same content block twice if you call this method multiple times + * unless `trackPageView()` is called meanwhile. This is useful for single page applications. + * + * Once you have called this method you can no longer change `checkOnScroll` or `timeIntervalInMs`. + * + * If you do want to only track visible content blocks but not want us to perform any automatic checks + * as they can slow down your frames per second you can call `trackVisibleContentImpressions()` or + * `trackContentImpressionsWithinNode()` manually at any time to rescan the entire DOM for newly + * visible content blocks. + * o Call `trackVisibleContentImpressions(false, 0)` to initially track only visible content impressions + * o Call `trackVisibleContentImpressions()` at any time again to rescan the entire DOM for newly visible content blocks or + * o Call `trackContentImpressionsWithinNode(node)` at any time to rescan only a part of the DOM for newly visible content blocks + * + * @param boolean [checkOnScroll=true] Optional, you can disable rescanning the entire DOM automatically + * after each scroll event by passing the value `false`. If enabled, + * we check whether a previously hidden content blocks became visible + * after a scroll and if so track the impression. + * Note: If a content block is placed within a scrollable element + * (`overflow: scroll`), we can currently not detect when this block + * becomes visible. + * @param integer [timeIntervalInMs=750] Optional, you can define an interval to rescan the entire DOM + * for new impressions every X milliseconds by passing + * for instance `timeIntervalInMs=500` (rescan DOM every 500ms). + * Rescanning the entire DOM and detecting the visible state of content + * blocks can take a while depending on the browser and amount of content. + * In case your frames per second goes down you might want to increase + * this value or disable it by passing the value `0`. + */ trackVisibleContentImpressions: function (checkOnSroll, timeIntervalInMs) { if (isOverlaySession(configTrackerSiteId)) { return; @@ -4749,7 +4791,14 @@ if (typeof Piwik !== 'object') { }); }, - // it must be a node that is set to .piwikTrackContent or [data-track-content] or one of its parents nodes + /** + * Tracks a content impression using the specified values. You should not call this method too often + * as each call causes an XHR tracking request and can slow down your site or your server. + * + * @param string contentName For instance "Ad Sale". + * @param string [contentPiece='Unknown'] For instance a path to an image or the text of a text ad. + * @param string [contentTarget] For instance the URL of a landing page. + */ trackContentImpression: function (contentName, contentPiece, contentTarget) { if (isOverlaySession(configTrackerSiteId)) { return; @@ -4767,10 +4816,16 @@ if (typeof Piwik !== 'object') { }); }, - // it must be a node that is set to .piwikTrackContent or [data-track-content] or one of its parents nodes - // we might remove this method again + /** + * Scans the given DOM node and its children for content blocks and tracks an impression for them if + * no impression was already tracked for it. If you have called `trackVisibleContentImpressions()` + * upfront only visible content blocks will be tracked. You can use this method if you, for instance, + * dynamically add an element using JavaScript to your DOM after we have tracked the initial impressions. + * + * @param Element domNode + */ trackContentImpressionsWithinNode: function (domNode) { - if (isOverlaySession(configTrackerSiteId)) { + if (isOverlaySession(configTrackerSiteId) || !domNode) { return; } @@ -4795,7 +4850,16 @@ if (typeof Piwik !== 'object') { }); }, - // name and piece has to be same as previously used on an impression + /** + * Tracks a content interaction using the specified values. You should use this method only in conjunction + * with `trackContentImpression()`. The specified `contentName` and `contentPiece` has to be exactly the + * same as the ones that were used in `trackContentImpression()`. Otherwise the interaction will not count. + * + * @param string contentInteraction The type of interaction that happened. For instance 'click' or 'submit'. + * @param string contentName The name of the content. For instance "Ad Sale". + * @param string [contentPiece='Unknown'] The actual content. For instance a path to an image or the text of a text ad. + * @param string [contentTarget] For instance the URL of a landing page. + */ trackContentInteraction: function (contentInteraction, contentName, contentPiece, contentTarget) { if (isOverlaySession(configTrackerSiteId)) { return; @@ -4812,10 +4876,21 @@ if (typeof Piwik !== 'object') { sendRequest(request, configTrackerPause); }); }, - // it must be a node that is set to .piwikTrackContent or [data-track-content] or one of its parents nodes - // we might remove this method again + + /** + * By default we track interactions on click but sometimes you might want to track interactions yourself. + * For instance you might want to track an interaction manually on a double click or a form submit. + * Make sure to disable the automatic interaction tracking in this case by specifying either the CSS + * class `piwikContentIgnoreInteraction` or the attribute `data-content-ignoreinteraction`. + * + * @param Element domNode This element itself or any of its parent elements has to be a content block + * element. Meaning one of those has to have a `piwikTrackContent` CSS class or + * a `data-track-content` attribute. + * @param string [contentInteraction='Unknown] The name of the interaction that happened. For instance + * 'click', 'formSubmit', 'DblClick', ... + */ trackContentInteractionNode: function (domNode, contentInteraction) { - if (isOverlaySession(configTrackerSiteId)) { + if (isOverlaySession(configTrackerSiteId) || !domNode) { return; } -- cgit v1.2.3