Skip to content
This repository has been archived by the owner on Aug 22, 2024. It is now read-only.

Home

Jump to bottom
Philip Lawrence edited this page Oct 17, 2012 · 2 revisions

Adobe SiteCatalyst Yii Extension

Welcome to the TagPla.net Adobe SiteCatalyst Yii Extension (or TPSiteCatalyst for short.) This provides developers an easy way to implement Adobe SiteCatalyst onto thier application or website. Check out our GitHub page for other analytics-based extensions, more documentation or to report a bug (or just say hi)! But first, we'll walk through a basic overview on how to install and use the tool so you can get Adobe SiteCatalyst up and running in no time.

Quick Links

Other Yii-Related Projects

Installation

Step 1: Upload the files

Simply unzip the files from the latest downloads into your extensions folder. You should now be able to navigate to protected/extensions/TPSiteCatalyst/components/ and see a file called TPSiteCatalyst.php You can also add in this extension as a Git Submodule. You can read more about that in the Installation wiki.

Step 2: Add in configuration

Within your configuration files (usually found under /protected/config/) there is the "components" section. 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:

'siteCatalyst' => array(
    'class' => 'ext.TPSiteCatalyst.components.TPSiteCatalyst',
    'rsids' => array(
                    'devsuite1',
                    'devsuite2',
               ),
),

Step 3: (Optional) Add in auto-render

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

  1. Configuration file - within the SiteCatalyst configuration, you must include:
'siteCatalyst' => array(
    'class' => 'ext.TPSiteCatalyst.components.TPSiteCatalyst',
    'rsids' => array(
                    'devsuite1',
                    'devsuite2',
               ),
    'autoRender' => true,
),
  1. Controllers - your controllers must have the following method:
<?php

protected function beforeRender($view)
{
    $return = parent::beforeRender($view);
    Yii::app()->siteCatalyst->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, simple add in the following line to it, before the return statement:

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

Configuration Options

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

class

The TPSiteCatalyst class location. Unless you change the installation directory, this does not need to change.

  • Required: yes
  • Type: string
  • Default: ext.TPSiteCatalyst.components.TPSiteCatalyst
s_account

The RSIDs to be set

  • Required: no
  • Type: string or array (see: Alternate variable syntaxes)
  • Format: varies
  • Default: (none)
s_codeLocation

The location of the s_code JavaScript file. If this is set to an empty string or not set, it is expected that the user will output the JavaScript file on their own.

  • Required: no
  • Type: string
  • Format: URL
  • Default: (none)
namespace

The Omniture namespace (default is s). This is rarely used and you likely don't need to set it.

  • Required: no
  • Type: string
  • Default: s
createObject

Automatically create the s (or whatever namespace) object. If set to false, var s = s_account([RSIDs]); will not be included and it is expected that the s object already exists;

  • Required: no
  • Type: boolean
  • Recommend Setting: true
  • Default: true
autoRender

Automatically render the SiteCatalyst 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)

  • Required: no
  • Type: boolean
  • Recommend Setting: true
  • Default: false
autoPageview

Automatically call the s.t() function within the code. By disabling this, you will need to output the s.t() call on your own.

  • Required: no
  • Type: boolean
  • Recommend Setting: true
  • Default: true
renderMobile

This is reserved for rendering a mobile pixel output (still a todo item)

  • Required: no
  • Type: boolean
  • Recommend Setting: false
  • Default: false
renderHead

This is for if you need to move the code up to the head tags or not. This is only in effect when autoRender is enabled. By default, the SiteCatalyst code will be placed at the end of the body tag.

  • Required: no
  • Type: boolean
  • Recommend Setting: false
  • Default: false

Usage

Accessing SiteCatalyst in Yii

Since the SiteCatalyst extension is setup as a component, you can simply use the following call to access the extension:

Yii::app()->siteCatalyst

Setting a SiteCatalyst variable

For Adobe SiteCatalyst, you set variables (object properties to be specific) to pass values. For the Yii extension you use a similar setup. All you need to do is set the name of the property to the value you want to pass.

A simple example

A normal call to set a custom variable in JavaScript:

s.eVar25 = 'fooBar';

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

Yii::app()->siteCatalyst->eVar25 = 'fooBar';
A more complex example

Often you need to push quite a bit of data into SiteCatalyst (which is why you might select using SiteCatalyst over something more simple like Google Analytics). With this extension, that is fairly easy.

For an example, let's push in transaction data 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:

<?php

// ...

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

public function actionCheckout( )
{
    // Do some processing here (let's say $order has information about the order)
    if($order->isComplete)
    {
        // Start the transaction using $order's information
        Yii::app()->siteCatalyst->purchaseID    = $order->OrderID;
        Yii::app()->siteCatalyst->transactionID = $order->OrderID;
        Yii::app()->siteCatalyst->city          = $order->BillingAddress->City;
        Yii::app()->siteCatalyst->zip           = $order->BillingAddress->Zip;
        
        // Loop through each item that the order had
        $products = array();
        foreach($order->Items as $item)
        {
            $products[] = array(
                'category'  => $item->Category->Name,
                'sku'       => $item->SKU,
                'quantity'  => $item->Quantity,
                'price'     => $item->Price,
            );
        }
        
        Yii::app()->siteCatalyst->products      = $products;
        
        // Add in the purchase event
        Yii::app()->siteCatalyst->events       = array('event25','purchase');
    }
}

Allowed Variables

A majority of the variables you get with a standard SiteCatalyst implementation are included here. These all have the same syntaxes as you would see in a JavaScript implementation. Some variables have an alternative syntax to provide an easier implementation, but checkout our Reference page for more on that. Below is a basic overview:

  • campaign
  • channel
  • currencyCode
  • eVarN (Where N = any number)
  • events
  • hierN (Where N = any number)
  • pageName
  • pageType
  • purchaseID
  • products
  • propN (Where N = any number)
  • s_account (set via settings/configuration)
  • server
  • state
  • TnT
  • transactionID
  • zip

Rendering the SiteCatalyst 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 SiteCatalyst JavaScript code. In almost all cases, you should use this in your main layout views (e.g. protected/views/layouts/main.php)

<script type="text/JavaScript">
<?php echo Yii::app()->siteCatalyst()->render(); ?>
</script>

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.

Quick Nav

Clone this wiki locally