tp-piwik-analytics A simple way to add Piwik Analytics to your application.

Piwik Extension

  1. Installation
  2. Usage
  3. Configuration Options
  4. Resources / Links
  5. Related TagPla.net Extensions

The TagPla.net Piwik Yii Extension (or TPPiwik for short) provides developers an easy way to implement Piwik Analytics into their application or website. Check out our GitHub page for the most up-to-date files and documentation. Otherwise, let's get started with a basic overview!

Installation

Step 1: Upload the files

The first step is straightforward; simply unzip the files from the latest downloads into your extensions folder. You should now be able to navigate to protected/extensions/TPPiwikAnalytics/components/ and see a file called TPPiwikAnalytics.php. You can also add in this extension as a Git Submodule. You can read more about that in the full installation instructions.

Step 2: Add in configuration

Find the "components" section within your configuration files (usually found under /protected/config/). Just like your db and cache components, we'll need to add in our own configuration for this. Add in the following code within the components section:

'piwik' => array(
    'class' =>'ext.TPPiwikAnalytics.components.TPPiwikAnalytics',
    'siteID' => '1',
    'trackerURL' => 'http://piwik.tagpla.net/piwik.js',
),

Of course, make sure to update the siteID and trackerURL values.

Step 3: (Optional) Add in auto-render

In order for the Piwik component to automatically render the code in the header, you must have the following two items configured:

  • Configuration file - Within the piwik configuration, you must include:
'piwik' => array(
    'class' =>'ext.TPPiwikAnalytics.components.TPPiwikAnalytics',
    'siteID' => '1',
    'trackerURL' => 'http://piwik.tagpla.net/piwik.js',
    'autoRender' => true,
),
  • Controllers - Your controllers must contain the following code:
protected function beforeRender($view)
{
    $return = parent::beforeRender($view);
    Yii::app()->piwik->render();
    return $return;
}

You can place this either within protected/components/Controller.php (or whichever Controller you are overloading) or within every single one of your controllers. In the event that you already have the method beforeRender within your controllers, simply add in the following line to it, before the return statement:

Yii::app()->piwik->render();

Usage

Accessing Piwik in Yii

Since the Piwik extension is set up as a component, you can simply use the following call to access the extension:

Yii::app()->piwik
Calling a Piwik method

In Piwik, you call various methods to change the settings and values that are passed to your severs. For the Yii extension, you use a similar setup. All you need to do is call the name of the method, then pass in the parameters (not as an array!)

A simple example

A normal call to set a custom variable in JavaScript: ~~~ [javascript] _paq.push(['setCustomVariable', 1, 'Section', 'Life & Style', 'page']); ~~~

Within a controller or view, you can do the same as the above via the extension:

Yii::app()->piwik->setCustomVariable(1, 'Section', 'Life & Style', 'page');
A more complex example

Sometimes you need to push quite a bit of data into Piwik. With this extension, that is fairly easy.

For example, let's push in a transaction when the user completes a checkout via the checkout action within the cart controller. You can see within this example that Yii's relational records can be used (see: $order->Store->Name):

protected/controllers/cart.php:

// ...

protected function beforeRender($view)
{
    $return = parent::beforeRender($view);
    Yii::app()->piwik->render();
    return $return;
}

public function actionCheckout( )
{
    // Do some processing here (let's say $order has information about the order)
    if($order->isComplete)
    {
        // Loop through each item that the order had
        foreach($order->Items as $item)
        {
            // And add in the item to pass to Piwik
            Yii::app()->piwik->addEcommerceItem(
                                                $item->SKU,
                                                $item->Name,
                                                $item->Category->Name,
                                                $item->Price,
                                                $item->Quantity
                                        );
        }
        
        // Log the transaction using $order's information
        Yii::app()->piwik->trackEcommerceOrder(
                                                $order->OrderID, 
                                                $order->Total, 
                                                ($order->Total - $order->ShippingAmount),
                                                $order->Tax, 
                                                $order->ShippingAmount, 
                                                $order->Discount
                                    );
    }
}
Disallowed methods

Nearly all of the methods are accessible via the extension. The exceptions are as follows:

  • Any deprecated method
  • Any method starting with get
  • trackLink
Rendering the Piwik output

Rendering within the extension depends on the way you configured it.

If Auto-Rendering is enabled

If auto-rendering is enabled and you followed the configuration steps (adding beforeRender call to your controllers) then there is nothing else for you to do to render the JavaScript code.

If Auto-Rendering is disabled

If you have auto-rendering disabled (which it is by default), then you can call the render() method within your views which will return the rendered Piwik JavaScript code. In almost all cases, you should use this in your main layout views (e.g. protected/views/layouts/main.php): ~~~ [html] ~~~

Note: The render method does not wrap <script></script> tags around the output. If auto-rendering is enabled, CClientScript::registerScript is utilized, otherwise JavaScript code is returned.

Configuration Options

This component allows for some flexibility within the configuration section. Below are all of the allowed configuration variables:

Required Options
  • class - The TPPiwikAnalytics class location

    • Type: string
    • Default: ext.TPPiwikAnalytics.components.TPPiwikAnalytics
  • siteID - Your site ID, as defined in Piwik

    • Type: integer
    • Default: (none)
  • trackerURL - The location of the piwik.js file

    • Type: string
    • Format: URL
    • Default: (none)
Optional Options
  • autoRender - Automatically render the Piwik code in the <head />. If you do set this to true, you will need to update your controller's beforeRender method (see: Optionally adding in auto-render code).

    • Type: boolean
    • Recommend Setting: true
    • Default: false
  • autoPageview - Automatically add trackPageView to the code. By disabling this, you will need to call Yii::app()->piwik->trackPageView(); for each page you want to track. Even when this is enabled, you can still call trackPageView with a specified page name and it will not call trackPageView twice.

    • Type: boolean
    • Recommend Setting: true
    • Default: true
  • variableName - Allow for multiple instances of Piwik code on the page via different variable names in JavaScript. See Piwik's Docs for more information.

    • Type: string
    • Recommend Setting: '_paq'
    • Default: '_paq'

Resources / Links

Related TagPla.net Extensions

4 0
6 followers
309 downloads
Yii Version: 1.1
License: MIT
Category: Others
Developed by: MisterPhilip
Created on: Oct 19, 2012
Last updated: 11 years ago

Downloads

show all

Related Extensions