Javascript Tracking Client

User guide

Read also the Javascript Tracking Client user guide to get familiar with the Javascript tracking client.

List of all Methods Available in the Tracking API

Requesting the Tracker Instance from the Piwik Class

  • Piwik.getTracker( trackerUrl, siteId ) - get a new instance of the Tracker
  • Piwik.getAsyncTracker() - get the internal instance of the Tracker used for asynchronous tracking

Using the Tracker Object

  • enableLinkTracking( enable ) - Install link tracking on all applicable link elements. Set the enable parameter to true to use a pseudo-click handler to track browsers (such as Firefox) which don't generate click events for the middle mouse button. By default only "true" mouse click events are handled.
  • trackEvent(category, action, [name], [value]) - Logs an event with an event category (Videos, Music, Games...), an event action (Play, Pause, Duration, Add Playlist, Downloaded, Clicked...), and an optional event name and optional numeric value.
  • trackPageView([customTitle]) - Logs a visit to this page
  • trackSiteSearch(keyword, [category], [resultsCount]) - Log an internal site search for a specific keyword, in an optional category, specifying the optional count of search results in the page.
  • trackGoal( idGoal, [customRevenue]); - Manually log a conversion for the goal idGoal, passing in the custom revenue customRevenue if specified
  • trackLink( url, linkType ) - Manually log a click from your own code. url is the full URL which is to be tracked as a click. linkType can either be 'link' for an outlink or 'download' for a download.
  • trackAllContentImpressions() - Scans the entire DOM for all content blocks and tracks all impressions once the DOM ready event has been triggered.
  • trackVisibleContentImpressions ( checkOnSroll, timeIntervalInMs ) - 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.
  • trackContentImpressionsWithinNode( domNode ) - 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.
  • trackContentInteractionNode( domNode, contentInteraction ) - Tracks an interaction with the given DOM node / content block.
  • trackContentImpression( contentName, contentPiece, contentTarget ) - Tracks a content impression using the specified values.
  • trackContentInteraction( contentInteraction, contentName, contentPiece, contentTarget ) - Tracks a content interaction using the specified values.

Configuration of the Tracker Object

  • setDocumentTitle( string ) - Override document.title
  • setDomains( array) - Set array of hostnames or domains to be treated as local. For wildcard subdomains, you can use: setDomains('.example.com'); or setDomains('*.example.com');
  • setCustomUrl( string ) - Override the page's reported URL
  • setReferrerUrl( string ) - Override the detected Http-Referer
  • setSiteId( integer ) - Specify the website ID. Redundant: can be specified in getTracker() constructor.
  • setApiUrl( string ) - Specify the Piwik HTTP API URL endpoint. Points to the root directory of piwik, e.g. http://piwik.example.org/ or https://example.org/piwik/. This function is only useful when the 'Overlay' report is not working. By default you do not need to use this function.
  • setTrackerUrl( string ) - Specify the Piwik server URL. Redundant: can be specified in getTracker() constructor.
  • setDownloadClasses( string | array ) - Set classes to be treated as downloads (in addition to piwik_download)
  • setDownloadExtensions( string ) - Set list of file extensions to be recognized as downloads. Example: 'doc|pdf|txt'
  • addDownloadExtensions( string ) - Specify additional file extensions to be recognized as downloads. Example: 'doc|pdf|txt'
  • setIgnoreClasses( string | array ) - Set classes to be ignored if present in link (in addition to piwik_ignore)
  • setLinkClasses( string | array ) - Set classes to be treated as outlinks (in addition to piwik_link)
  • setLinkTrackingTimer( integer ) - Set delay for link tracking in milliseconds.
  • discardHashTag( bool ) - Set to true to not record the hash tag (anchor) portion of URLs
  • setGenerationTimeMs(generationTime) - By default Piwik uses the browser DOM Timing API to accurately determine the time it takes to generate and download the page. You may overwrite the value by specifying a milliseconds value here.
  • appendToTrackingUrl(appendToUrl) - Appends a custom string to the end of the HTTP request to piwik.php?
  • setDoNotTrack( bool ) - Set to true to not track users who opt out of tracking using Mozilla's (proposed) Do Not Track setting.
  • disableCookies() - Disables all first party cookies. Existing Piwik cookies for this websites will be deleted on the next page view.
  • deleteCookies() - Deletes the tracking cookies currently currently set (this is useful when creating new visits)
  • killFrame() - Enables a frame-buster to prevent the tracked web page from being framed/iframed.
  • redirectFile( url ) - Forces the browser load the live URL if the tracked web page is loaded from a local file (e.g., saved to someone's desktop).
  • setHeartBeatTimer( minimumVisitLength, heartBeatDelay ) - records how long the page has been viewed if the minimumVisitLength (in seconds) is attained; the heartBeatDelay determines how frequently to update the server
  • getVisitorId() - returns the 16 characters ID for the visitor
  • getVisitorInfo() - returns the visitor cookie contents in an array
  • getAttributionInfo() - returns the visitor attribution array (Referer information and / or Campaign name & keyword).
  • getUserId() - returns the User ID string if it was set.
  • setUserId( userId ) - Sets a User ID to this user (such as an email address or a username).

    Attribution information is by Piwik to credit the correct referrer (first or last referrer) to any goal conversion.

    You can also use any of the following functions to get specific attributes of data:

    • piwikTracker.getAttributionCampaignName()
    • piwikTracker.getAttributionCampaignKeyword()
    • piwikTracker.getAttributionReferrerTimestamp()
    • piwikTracker.getAttributionReferrerUrl()
  • setCustomVariable (index, name, value, scope) - Set a custom variable.

  • deleteCustomVariable (index, scope ) - Delete a custom variable.
  • getCustomVariable (index, scope ) - Retrieve a custom variable.
  • storeCustomVariablesInCookie() - When called then the Custom Variables of scope "visit" will be stored (persisted) in a first party cookie for the duration of the visit. This is useful if you want to call getCustomVariable later in the visit. (by default custom variables are not stored on the visitor's computer.)
  • setCampaignNameKey(name) - Set campaign name parameter(s). (Help: Customize Campaign name parameter names)
  • setCampaignKeywordKey(keyword) - Set campaign keyword parameter(s). (Help: Customize Campaign keyword parameter names)
  • setConversionAttributionFirstReferrer( bool ) - Set to true to attribute a conversion to the first referrer. By default, conversion is attributed to the most recent referrer.

Configuration of Tracking Cookies

Starting with Piwik 1.2, first party cookies are used. Consideration must be given to retention times and avoiding conflicts with other cookies, trackers, and apps.

  • setCookieNamePrefix( prefix ) - the default prefix is 'pk'.
  • setCookieDomain( domain ) - the default is the document domain; if your web site can be visited at both www.example.com and example.com, you would use: tracker.setCookieDomain('.example.com'); or tracker.setCookieDomain('*.example.com');

  • setCookiePath( path ) - the default is '/'.

  • setVisitorCookieTimeout( seconds ) - the default is 13 months
  • setReferralCookieTimeout( seconds ) - the default is 6 months
  • setSessionCookieTimeout( seconds ) - the default is 30 minutes

Advanced uses

  • addListener( element ) - Add click listener to a specific link element. When clicked, Piwik will log the click automatically.
  • setRequestMethod( method ) - Set the request method to either "GET" or "POST". (The default is "GET".) To use the POST request method, the Piwik host must be the same as the tracked website host (Piwik installed in the same domain as your tracked website).
  • setCustomRequestProcessing( function ) - Set a function that will process the request content. The function will be called once the request (query parameters string) has been prepared, and before the request content is sent.
  • setRequestContentType( contentType ) - Set request Content-Type header value. Applicable when "POST" request method is used via setRequestMethod.

Unit Tests Covering piwik.js

The Piwik JavaScript Tracking API is covered by an extensive JavaScript unit test suite to ensure that the code quality is as high as possible, and that we never break this functionality. Tests are written using QUnit. To run the tests, simply checkout the Piwik Git repository and go to /path/to/piwik/tests/javascript/. Tests are run inside your browser.

The Piwik JavaScript API has been tested with numerous web browsers. To maximize coverage, we use services like crossbrowsertesting.com and browsershots.org.

Minify piwik.js

The piwik.js is minified to reduce the size that your website visitors will have to download. The YUI Compressor is used to minify the JavaScript (more information). You can find the original non minified version in /js/piwik.js.