# Piwik Plugin #
A drop-in plugin to add a [Piwik](http://piwik.org) tracker to your presentation layer. To use this plugin, you'll
need to have a Piwik server installed and running.
## Installation ##
* Install the plugin
{{{
symfony plugin:install sfPiwikPlugin -s=beta
}}}
Since the plugin is still in alpha mode, the install requires a `-s=beta` parameter.
* Add the sfPiwikFilter to your filter chain in `filters.yml`
{{{
#!yaml
...
# insert your own filters here
sf_piwik_plugin:
class: sfPiwikFilter
...
}}}
* Configure your `app.yml`
{{{
#!yaml
all:
sf_piwik_plugin:
enabled: on
tracker_url: example.com/piwik/
site_id: 1
}}}
- **tracker_url** is where the Piwik server is located. Do not inlcude the protocol prefix (http://).
- **site_id** is the ID of your site in the Piwik installation
## Advanced Usage ##
* Module/Action-level Configuration
There are various Piwik attributes that can be set at the module or action level by configuring the
[`module.yml`](http://www.symfony-project.org/book/1_2/05-Configuring-Symfony#chapter_05_sub_module_configuration)
file.
{{{
#!yaml
all:
sf_piwik_plugin:
params:
# any of the optional params in app.yml can go here
# this configures the entire module
action_name:
sf_piwik_plugin:
params:
# any of the optional params in app.yml can go here
# this configures a specific action within a module
}}}
* Configurable Parameters
Read the [Javascript](http://piwik.org/docs/javascript-tracking/) docs on the Piwik website for further
details on these parameters.
- **insertion** - Position of the tracking code within the HTML `<body>`. (default=bottom)
- **custom\_data** - Any value that will be sent in the `data` response var. You'd only use this if you've
developed a custom Piwik plugin or are using one that requires this field be set.
- **document\_title** - Customize the page name displayed in Piwik.
- **domains** - Consider a host an "alias" host and not record the links to this domain as "outlinks".
- **download\_classes** - Set classes to be treated as downloads (in addition to piwik_download).
- **download\_extensions** - Set list of file extensions to be recognized as downloads.
- **ignore\_classes** - Set classes to be ignored if present in link (in addition to piwik_ignore).
- **link\_classes** - Set classes to be treated as outlinks (in addition to piwik_link).
- **link\_tracking\_timer** - Set delay for link tracking in milliseconds.
- **enable\_link\_tracking** - Install link tracking on all applicable link elements. (default=on)
- **campaign\_name** - Set a campaign name.
- **campaign\_keyword** - Set a campaign keyword.
- **before\_tracker\_js** - Javascript code to be executed immediately before the tracker is invoked.
- **after\_tracker\_js** - Javascript code to be executed immediately after the tracker is invoked.
- **force** - Forces tracker code to be inserted in the respose even if the request type is "not trackable".
See sfPiwikTracker::isTrackable().
- **no\_init** - If true, JS tracker initialization code is not inserted in the response. This is automatically
set to true if the **force** parameter is on and the current request is XHR.
* Accessing the Tracker
At some point, you might want to be able to access the tracker instance from your code to perform some complex
things. Here's how you'd do that:
{{{
#!php
<?php
class myActions extends sfActions
{
public function executeIndex($request)
{
// get the tracker instance from the context
$tracker = sContext::getInstance()->get(sfPiwikTracker::NAMESPACE);
// you can get or set any of the optional parameters
$tracker->setDocumentTitle("My Title");
}
}
}}}
* Tracker Events
Just before the tracker writes the Javascript to the response body, it fires an event to notify listeners of the
last chance to modify tracker parameters. The event fired is `piwik_filter.inserting`.
Read the [Events](http://www.symfony-project.org/book/1_2/17-Extending-Symfony) section from the Symfony guide to
understand how events work.