HOWTO: Hack Metrics for More Detail

Do you know which of your posts have been viewed most? Which categories (if your blog supports them) are most popular? How about where your visitors are geographically situated?

If you use Performancing Metrics to monitor how your blog is being viewed, you do. I use them, and I’m learning a lot about my readers’ interests.

Today I’m going to look at my ‘Post Views’, i.e., which posts (articles) are attracting the most reader attention. We’ll begin by looking at the default Performancing Metrics script. I use WordPress as my blogging engine so my default script reflects the WordPress API. If you use another blogging engine (such as Drupal or Moveable Type) I’m going to assume that you can translate the concepts in this article into code for your specific blogging engine.

DEFAULT METRICS SCRIPT

When I first signed-up to use Performancing Metrics, here’s the script they gave me (please note that the line numbers are for our reference only and are not part of the original script):

01    <script type="text/javascript">
02    <?php
03    global $userdata;
04    if ($userdata) {
05        echo "z_user_name=\"" . $userdata->display_name . "\";\n";
06        echo "z_user_email=\"" . $userdata->user_email . "\";\n";
07    }
08    ?>
09    z_post_title="<?php the_title();?>";
10    z_post_category="<?php $c=get_the_category();echo $c[0]->cat_name;?>";
11    </script>
12    <script id="stats_script" type="text/javascript" src="http://metrics.performancing.com/wp.js"></script>

Please notice line number 9 (“09”). That line populates a javascript variable called ‘z_post_title’ with the result of a PHP call to a WordPress function called ‘the_title()’, which returns — yes, you guessed it! — the title! You may be wondering, as I did: what title? of the page? of the post? of the archive? of the category? of the search results?

Hm… welcome to the confusion that would soon dominate my blog-metrics world. You see, WordPress’s ‘the_title()’ function returns the title of the current blog post. Which is absolutely perfect if we’re looking at an individual post. The challenge here is that not everyone who visited my blog was visiting individual posts. Some people came to the home page and read entire posts from there… others came through search engine results and went right to the post itself or, in some cases, were directed to the category archive or a monthly archive on my blog.

MYSTERIOUS POPULARITY

After using the default Performancing Metrics script for a few weeks, I found myself viewing my ‘Post Views’ panel with some surprise: posts that I thought would be more popular with my readers sometimes appeared as though they weren’t popular, while other posts that I thought would be less interesting seemed to be getting a lot of unanticipated attention.

Here are a couple of screen shots showing my first week’s Performancing Metrics using the default script for a WordPress blog:

Please notice that every post being counted in this ‘Post Views’ panel is identified only by the the post’s title, i.e., the_title(). There’s nothing at all wrong with title-only nomenclature but as we will soon see, it’s hiding some rather significant details.

It turns out that calling WordPress’s ‘the_title()’ function from any page with more than one post on it — whether the blog homepage, or a category archive, or a date archive, or even a search result — will return only the top-most post’s title on the current blog page.

As I thought more carefully about the mysteriously skewed popularity of my posts, I realized what was going on. This is a subtle point that came upon me as an ‘aha!’ moment and if you haven’t already had the same flash of insight, hold on to your hat!

Let’s say I write just 2 posts a day. I check the online news sources for interesting items. I find one and write about it, publishing to my blog sometime around 8:00am. It’s a real gem of a story and I think to myself, “Wow! My readers are gonna LOVE this!”

About 30 minutes later I find another interesting item. It’s not nearly as significant as the first post I made just a half-hour earlier but I think to myself, “This is kinda cool. It’s not as important as the first post today but maybe some of my readers will find the less-intense content refreshing.” So again I write and publish a post, and off to work I go.

At the end of the day I check my Performancing Metrics numbers on the ‘Post Views’ panel and what do I find? Only a few people seemed interested in the first post but a whole lot more seemed to visit the second post.

I feel a bit confused by these numbers. Do I not really understand my target audience? Do I think I’m writing for one audience but am really getting the attention of another altogether? It seems inconceivable to me that my readers would prefer the second, less-intense post over the first one.

But numbers don’t lie, and there before me are the cold, hard facts. How can I argue with numbers?

DETAIL BEHIND THE NUMBERS

Well, I can’t. And upon further reflection I realized that I didn’t have to.

That first post had been the top-most post on my blog for all of about 30 minutes, while the second post had been top-most on my blog for the remainder of the day — of course! no wonder the numbers looked like they did!

Here’s the subtle but very important conclusion: every time someone visited my blog’s homepage, they would have a chance to read both stories but… the default Performancing Metrics script would capture ‘the_title()’ of the top-most post on the page and tally a view for that, and only that, post.

Both articles may’ve been read… neither one might’ve been read… perhaps only one or the other was read but I couldn’t tell from the Performancing Metrics tally because a view to my blog’s homepage was equivalent — from the Metrics standpoint — with a view of that post alone.

By now you might’ve guessed that if a reader were to have visited that second post’s page, the tally would accrue just as it had for visiting the homepage when that second post was top-most on the page. This effect was magnified even more if a day went by where I didn’t post at all: the last post from the previous day would seem to jump off the scale in popularity with every visit to my blog’s homepage.

TWEAKING METRICS FOR DETAILS

Although I’ve made my living as a software developer since the mid 1980’s, web development hasn’t been a part of my job description. If I was going to attempt to modify my default Performancing Metrics script so that it would give me finer distinctions in the numbers it tracked, I was going to have to learn the PHP scripting language. Specifically, I was going to have to research the WordPress API functions that I’d need to call in order to get this increased granularity that I desired from my Metrics numbers.

If all that I’ve described makes sense to you so far… if you’re nodding your head up and down in agreement that you also want to benefit from this additional level of detail in your Metrics, then let me tell ya: have I got a solution for you!

It took me a few days of reading and experimenting with PHP and with WordPress function calls. I often interrupted a co-worker who was much more experienced with PHP than I was, in order to get an informed sense of direction or a quick answer to an otherwise newbie question. The result of all this time and effort is this modified version of the original Performancing Metrics script (it is a mixture of javascript and php; for those of you unfamiliar with either or both, let’s discuss questions in the comments vs. me trying to anticipate questions and answer them here; this, in order to keep the article as brief as possible — thanks in advance for your understanding!):

001    <script type="text/javascript">
002    /* --------------------------------------------------------------------------------------------
003        2006-03-31~rch: use custom title and category labels to distinguish between actual page
004        visits and accidental visits previously tracked when an archive (homepage, search, monthly
005        or daily archives, etc.) are browsed; script developed with help from I.McFadden.
006    
007        original code:
008
009            z_post_title="<?php the_title();?>";
010            z_post_category="<?php $c=get_the_category();echo $c[0]->cat_name;?>";
011    
012        new code:
013    -------------------------------------------------------------------------------------------- */
014    
015    <?php
016        if ( is_home() ) {
017    ?>
018            // adds "Homepage (" prefix and ")" suffix to post title, and
019            // sets category tracker to custom string (in this case "~HomePage"):
020            z_post_title="Homepage (<?php the_title();?>)";
021            z_post_category="~HomePage";
022    
023    <?php
024        } elseif ( is_single() ) {
025    ?>
026            // just prints the title all by itself while setting
027            // the category to the first one listed in the POST's
028            // category array
029            // NOTE: this is the default Performancing Metrics behavior.
030            // --- TO DO --- is there a way to list all categories assigned to
031            //               a post such that all categories, collectively, are
032            //               being tracked by Performancing ???
033            z_post_title="<?php the_title();?>";
034            z_post_category="<?php $c=get_the_category();echo $c[0]->cat_name;?>";
035    
036    <?php
037        } elseif ( is_category() ) {
038    ?>
039            // adds "Category: " prefix and prints only the category of
040            // the PAGE (vs. of the POST); no title printed because seems
041            // irrelevant to the tracking of category views vs. specific
042            // post views:
043            z_post_title="Category: <?php the_category();?>
044            z_post_category="<?php single_cat_title();?>";
045    
046    <?php
047        } elseif ( is_search() ) {
048    ?>
049        // adds "Search: " prefix and user's actual search term(s), while
050        // setting category to custom string "~Search":
051        z_post_title="Search: <?php echo wp_specialchars($s);?> (<?php the_title(); ?>)";
052        z_post_category="~Search";
053    
054    <?php
055        } elseif ( is_month() ) {
056    ?>
057            // adds "Month: " prefix followed by the actual date that, for
058            // my taste, is formatted as "31 March 2006", and sets Category
059            // to "~Month":
060            z_post_title="Month: [<?php echo date("d M Y");?>]";
061            z_post_category="~Month";
062    
063    <?php
064        } elseif ( is_day() ) {
065    ?>
066            // adds "Day: " prefix followed by the actual date that, for
067            // my taste, is formatted as "31 March 2006", and sets Category
068            // to "~Day":
069            z_post_title="Day: [<?php echo date("d M Y");?>]";
070            z_post_category="~Day";
071    
072    <?php
073        } else {
074    ?>
075            z_post_title="(?<?php the_title();?>)";
076            z_post_category="~Unknown";
077    
078    <?php
079        }
080    ?>
081    // end change.
082    
083    </script>
084    
085    <script id="stats_script" type="text/javascript" src="http://metrics.performancing.com/wp.js"></script>

In contrast with the earlier ‘Post Views’ panel we saw, here’s how Performancing Metrics now labels my blog’s numbers:

Whereas before every entry was a post title and nothing more, now these descriptors include context markers like “Homepage (” in front of the title to show, when a user viewed the homepage, which post was at the top of the page at the time. It also shows things like when a user has viewed a date-driven archive by prefixing either “Month: [” or “Day: [” in front of the post title. Similar results are obtained if the user views by category or by searching for something.

I thought that was pretty useful for my purposes. I also realize that there’s probably a lot more that one could add to this script to polish and tailor it even more so if any of you PHP or WordPress or javascript gurus want to build on this, or refine it further, I welcome your changes.

That’s all, folks! Enjoy!