How to Use eZ Publish Extensions: Google Analytics

Brookins Consulting has created an extension called BC Website Statistics, licensed under the GPL, that we are happy to share with the eZ Publish community. This tutorial is the second in the eZ Publish “How to” series. The first article ( How to Configure an eZ Publish Site) described basic setup of an “eZ Tennis Club” website. In this tutorial we will add the BC Website Statistics extension to the eZ Tennis Club site. You will also learn how to use the Google Analytics service and gain a general understanding of the eZ Publish extension system.

Definitions

Google Analytics (GA) - A free service offered by Google that generates detailed statistics about website visitors. One major advantage is that a webmaster can optimize his or her AdWords advertisement and marketing campaigns through the use of GA's analysis of where visitors came from, how long they stayed on the website and their geographical location.
Extension - A code component that “plugs in” to the eZ Publish core, providing custom application components and configurations.
Template operator – A mechanism that takes input, transforms it, and returns the result to the template. Template operators are programmed in PHP and are simple to create and plug in to the eZ Publish template system. eZ Publish has many built-in template operators.

Prerequisites

In order to get the most out of this tutorial:

Perform the steps described in the first article in this series, How to Configure an eZ Publish Site.
You must have access to the eZ Publish files on the file system.
You must have access to the eZ Publish Administration Interface.
Basic knowledge about the eZ Publish template language and / or PHP is useful, but not necessary.

Keep in mind that the interfaces, buttons, screenshots and procedures may vary from those found in this article if you use a version other than eZ Publish 3.9.2 and the Website Interface 1.2. In most cases these variations will be minor and we encourage you to always work with the latest stable version available.

Setting up a Google Analytics account

Let's assume that you are the webmaster of the eZ Tennis Club website. You want to know more about the features that attract and maintain the site’s international audience.

To gather this information, you need to collect page statistics either using page tagging or web server log file analysis. The former method – page tagging – can be used in conjunction with Google Analytics, and is the topic of this article. Log file analysis is another (and more traditional) method for analyzing site activity (although not discussed in this article). Awstats is a popular tool for performing this kind of analysis.

Using Google Analytics

Google Analytics is a JavaScript-based client-side statistics collection tool. It is enabled by adding a snippet of JavaScript code to every page on a website. This code sends statistical information to Google whenever a page is loaded in a visitor’s web browser.

Google Analytics is an excellent solution to the problem of finding a simple, inexpensive way to perform website statistics collection. It also includes advanced tracking and reporting features that are not currently available via the traditional method of log file analysis.

Goals are important

Whether it's selling specific types of products, tracking user registration, learning the frequency of incomplete webshop checkouts or simply tracking specific URLs on a website, there are many possible tracking goals.

Before you begin measuring your site statistics, think about why you are measuring. Document your site goals, and plan what you are going to do with the results of the measurements. With a set of goals, you can use the information from Google Analytics to iterate through enhancement and measurement cycles.

For the eZ Tennis Club, the tracking goals are initially simple – we want to track international visitors, since one of the club's goals is to provide events, services, and news for a worldwide audience. We also want to find out how effective specific marketing activities are at promoting certain events. Generally, we want to know more about who is visiting the site, where they are from, and what they are looking for. We will keep this in mind for near the end of this tutorial, when we look at a few basic Google Analytics reports.

You can sign up for a free Google Analytics account at http://www.google.com/analytics/. If you do not already have a Google account (which is also free), then you must sign up for that first. Once you have activated and logged in to your Google Analytics account, click the Add Website Profile link, then enter the URL of your site and click the Continue button.

You should then see a page with some code in a text area. What you will need in order to configure the BC Website Statistics extension is the Urchin key, which is the value in quotation marks on this line:

_uacct = "your-urchin-key";

eZ Publish extensions are packages containing functionality that extend or alter the features of an eZ Publish site. eZ Publish is designed with a “plug-in” architecture, so that the system can be customized without affecting the core installation. After installation, extensions are either automatically detected by convention or specified via settings.

Extensions can provide custom functionality using the existing standard system of templates, designs, template operators, classes, datatypes, modules, fetches, extended attribute filters, views, workflow events, shop account handlers, shipping handlers, tax handlers, output handlers, login handlers, cli scripts, cronjobs, notifications, search engines, libraries, SQL files, packages, settings, patches and more.

This article does not describe how to create an extension. Instead, it explains how to install and use extensions created by other eZ Community members – specifically Brookins Consulting’s BC Website Statistics extension. If you want to learn how to create extensions, you can analyze the source code of existing eZ Publish extensions and refer to the documentation and other eZ Publish educational resources (such as the eZ Publish Basics book). Alternatively, there is a network of global eZ Partners who are available to build extensions according to your specifications.

Where to find extensions

There are a number of sources for obtaining extensions to eZ Publish. These include supported partner certified solutions and community-supported projects, contributions, SVN respository and public SVN repository.

Installing an extension

This section describes how to install the BC Website Statistics extension on our eZ Tennis Club site. Most eZ Publish extensions are installed in a similar manner.

Download the extension's latest binary package file in the preferred format ( .tar.gz, tar.bz2 or .zip ).
Unpack the package into the extension/ directory in the eZ Publish installation. This should create a directory with the extension name bcwebsitestatistics. If not, rename the directory.
On Unix-like operating systems, set file ownership of the extension directory (bcwebsitestatistics) recursively to the owner and group of the webserver. For example, if the webserver owner and group are both named “apache”, type this command from the extension directory: chown -R apache:apache bcwebsitestatistics. Otherwise, set the access permissions to 750 (chmod 750 bcwebsitestatistics).

Activating an extension

Extensions can be activated globally (which will affect every site – including translated sites – running from the eZ Publish installation) or can be activated for one or more specific siteaccesses.

There are two ways to activate extensions:

Use the Administration Interface.
Manually edit the site configuration files for either specific siteaccesses or globally.

When you activate an extension through the Administration Interface, it will be activated for all siteaccesses.

When you manually enable an extension, you have greater control over the siteaccesses to which the extension applies. This gives you more granular control over the impact of the extension. As stated in the first article in this series, site settings follow an override order, where basic settings are overriden by siteaccess settings, which are overridden by global settings. Therefore, to enable the extension in only the “eng” siteaccess of the eZ Tennis Club site, we would edit settings/eng/site.ini.append.php and add an entry to the ActiveAccessExtensions[] array under the [ExtensionSettings] block:

[ExtensionSettings]
ActiveAccessExtensions[]
ActiveAccessExtensions[]=bcwebsitestatistics 
ActiveAccessExtensions[]=ezwebin

For the sake of this tutorial, we will activate the extension for all siteaccesses via the eZ Publish Administration Interface. To do so, click the Setup link on the top navigation bar. On the left menu, click the Extensions link. In the Available extensions window, mark the checkbox under the Activate column that corresponds to the bcwebsitestatistics extension. (Note that the extension name displayed in the Administration Interface corresponds to the directory name where the extension was installed.) Click the Apply changes button.

Configuring extension settings

Copy the configuration file extension/bcwebsitestatistics/settings/bcwebsitestatistics.ini.append.php into the eZ Publish settings/override/ directory.
Edit the bcwebsitestatistics.ini.append.php configuration file. Replace the value of the Urchin setting with the value provided by Google Analytics for your own website profile, as described earlier in this tutorial. As an example:

[BCWebsiteStatisticsSettings]
# Required Settings Change
Urchin=UA-2639251-2

# Default Settings
OrderSubmit=enabled 
PageSubmit=enabled 

# Optional Settings
# HostName=example.com 
HostName=disabled 
ShopName=eZPublishSite

Installing the template operator

The BC Website Statistics extension primarily consists of a template operator for the standard design. It could be considered a template operator extension.

If you are using a custom design extension (other than the Website Interface extension), you should create a pagelayout.tpl template override. Template overrides (see the documentation) and creating extensions (see the eZ Publish Basics book) are beyond the scope of this article. Therefore, in this article we will modify the pagelayout.tpl template for the Website Interface extension for the eZ Tennis Club site. However, on a real installation, you should do this through a template override because this file gets overwritten when you upgrade the Website Interface.

Place the template operator code {'false'|bc_ga_urchin()} as the last code element before the </head> tag in the extension/ezwebin/design/ezwebin/templates/pagelayout.tpl file.

{foreach ezini( 'JavaScriptSettings', 'JavaScriptList', 'design.ini' ) as $script} 

   <script language="javascript" type="text/javascript" src={concat( 'javascript/', $script )|ezdesign}></script>
{/foreach}

{* The following is the required bcwebsitestatistics template operator *}
{'false'|bc_ga_urchin()} 
</head>
<body> 


<!-- Complete page area: START -->

Testing the extension

To test that the BC Website Statistics extension has been correctly installed and configured:

Clear the INI and template caches. In the Administration Interface, expand the Clear cache window if necessary, select Ini settings from the drop-down menu, then click the Clear button. Repeat this step twice but select Template and Static from the drop-down menu. As clearing all of the caches is resource-intensive, we do not want to clear all of the caches unless it is absolutely necessary, especially on large, busy sites.
Log in to the Google Analytics website and confirm the correct installation of the template code by clicking the Edit link for your site under the Settings column. Then, click the Check status link.

Testing the page statistics

Browse your site, loading several pages in order to generate activity that will be reported by Google Analytics. You will have to wait up to 24 hours after your first round of testing for the service to store and display the statistics in your reports.

Debugging

If no statistics are reported by Google Analytics, the first thing to check is that you cleared the cache after installing the extension and template operator into the design template.

Then, check whether your template override for the pagelayout.tpl file is being recognized by the system. While viewing your site in a browser, right-click on an empty spot and select “View Page Source” (or the menu item specific to your browser). Then, look for this code:

<script src="http://www.google-analytics.com/urchin.js" type="text/javascript">

If that code is not present, enable template debugging by adding the following settings to the settings/override/site.ini.append.php file then clear the Ini settings and Static caches.

[DebugSettings]
DebugOutput=enabled

[TemplateSettings]
Debug=enabled
ShowUsedTemplates=enabled 
ShowXHTMLCode=disabled

Upon enabling the debug output, you will see a list of used templates, source code comments containing the path of templates used and general debug warnings, notices and errors. This information can be used to determine the cause of problems.

Google Analytics provides a portal for viewing reports on website activity. The portal uses dynamic HTML, JavaScript and Flash to provide access to a set of reports that describe various types of activity on your site.

With Google Analytics, the eZ Tennis Club site can track basic information such as page views, but also perform much more sophisticated operations, like gathering webshop statistics, setting goals, measuring the success of Google AdWords campaigns, seeing how much time people are spending on the site, exporting reports and more. Statistics can be filtered by many different properties, such as by specific keyword or URL, in order to produce refined results. This is documented in the Google Analytics Help Center.

In this tutorial, we will give a brief tour of some of the basic Google Analytics functionality and show you how to set up automatic report generation.

After logging into your Google Analytics account, click the View Reports link for your site.

The left menu of the reporting interface provides access to information about who your visitors are (the Visitors item), how they got to your site (the Traffic Sources item), and which pages they are accessing (the Content item). We will describe one of the pages under each of these sections. We strongly encourage you to explore the Google Analytics documentation and interface, as this article only presents a small portion of what can be done.

Under the Visitors menu item, the Map Overlay page is a visual representation of where site visitors are located. Since the eZ Tennis Club wishes to attract an international audience, it can track the progress of its efforts in reaching the different parts of the globe.

Under the Traffic Sources menu item, on the Search Engines page, you can see which search terms visitors are using in order to find your site. The eZ Tennis Club is able to use this information to reveal what people are looking for when they come to the site. They can then make decisions regarding what keywords they need to target more, or perhaps what unexpected topics could be expanded upon in order for the club to reach a broader audience.

Under the Content menu item, the Top Content page shows which URLs are the most popular on a site. If the eZ Tennis Club were to run a marketing campaign to promote an upcoming tournament, it could direct all interested visitors to a specific tournament page, such as http://tennisdemo.ezsystems.ca/eztourney. Using Google Analytics, it could then gauge the success of that marketing campaign based on how many people visited that page and how much time they spent on that page.

Email reports

You can configure one-time or scheduled customized email reports with a variety of report export formats. Simply click the Email button on almost any report view. This will send an email with an attached report.

If you click the Schedule tab, you can send periodic reports to interested parties in order to track regular progress on your website.

Exportable reports

You can export reports into a variety of output formats including PDF, CSV, XML and TSV. Simply click the Export button on almost any report view and select the desired report format by clicking the export format link. This will open a new window prompting you to save the exported report file.

In this article, we set up visitor tracking on the fictional eZ Tennis Club site powered by eZ Publish using Google Analytics.

With the BC Website Statistics extension installed and configured within your eZ Publish installation, your website will transmit page statistics to the Google Analytics service. You should now have gained some experience and understanding with the following features within eZ Publish:

Administration Interface
INI settings files
Template files
Template operators
Extensions

Subsequent articles in this tutorial series will explain other ways to enhance eZ Publish websites, including workflows, community features, RSS feeds and more!

Conclusions

We hope this tutorial has been helpful and interesting to the eZ Publish community, providing useful information about extensions, the BC Website Statistics extension and the Google Analytics service. We invite you to leave a comment or question about anything in this article.

Brookins Consulting makes implementing statistics services within eZ Publish simple with the BC Website Statistics extension.

Resources