Help

Contents

This document is split into a few parts in order to make it easier to reference. Please see the last section to contact the author if you're still having trouble.

  1. Description
  2. Quick Start Video
  3. Installation
  4. Code Structure
  5. The Main Interface
  6. The Site Manager
  7. Other Screens
  8. Setting Up Your Cron Job
  9. Further Support

Description

SiteSearchStats is a PHP web application that tracks your sites' metrics on the most popular search engines and social networks. All of your statistics are graphed and displayed in a beautiful HTML5/CSS3 template that makes it easy to identify where your sites are performing, and where they need improvement.

Features

Metric Tracking

With SiteSearchStats, you can track the following metrics:

Track Unlimited Sites

With SiteSearchStats, you can track an unlimited number of your sites, and use the powerful interface to compare one, or all of your sites' statistics.

XML Engine

SiteSearchStats relies on PHP5 + with the included SimpleXML engine to store data in an XML file, negating the need for a complicated MySQL database. Additionally, an easy-to-setup cron job is included to refresh your stats on a daily basis.

Beautiful Look

SiteSearchStats aims to be the easiest, most aesthetically-pleasing way to track how your websites are doing day-by-day.

Easy To Use Demo Mode

SiteSearchStats includes an easy to use demonstration mode that allows you or your clients to add sites, but have them deleted at a set interval. You can also choose to disallow adding of sites.

Requirements

Quick Start Video

Watch this video on how to get your SiteSearchStats installation up and running in under two minutes.

Installation

Installing SiteSearchStats is a painless process - just unzip and configure. After unzipping the downloaded archive to a folder, open up /includes/config.php to change around any options you'd like to tweak.

It's recommended that you replace the API keys provided with the application with your own - if the API keys provided reach their limit for the day, and your app uses them afterwards, you won't get valid data.

API Key Signup Links

Cron Setup

If you don't want to manually load your sites' data every day, you'll need to set up a cron job. Don't forget to visit that section of this Help page near the bottom.

Getting Started

If you'd like to skip ahead and add your first site, scroll down to Site Manager and add your first site to add today's data.

Code Structure

SiteSearchStats was designed from the outset for tweaking. You should find it relatively easy to add your own metrics. The code has been extensively commented - no one likes guessing how code works!

It's probably easiest if each folder/file is listed below, with a comment about each's purpose. The folders containing code to execute the project are:

Root Folder Files - The Interface

/includes - The Beef!

/js - Interface Code

The Main Interface

SiteSearchStats - Main Interface

This screen holds the graphing and statistics views of your data. Your data trends are beautifully displayed in chart and table form. The screen is split into four main parts: the menu, the graph, the data, and the footer.

The Menu

The menu contains links to load different parts of the application, and also contains the dropdown selectors for choosing different Dates, Metrics, and Sites. Please note: clicking either Main or changing any options in the Dropdowns will automatically return you to this Main interface to display the data you have selected.

The Graph

The graph is rendered using flot and chooses the colors automatically. It graphs whatever data is selected according to the dropdown menu selections.

Note: Both the graph and the data display combined numbers for all sites selected in the Sites dropdown.

The Data

The data portion of the app contains a tabular rendition of the statistics your sites are seeing. Black numbers indicate no change from the previous data point, green numbers indicate a rise, and red numbers indicate a decline. If a site doesn't have an optional metric filled out, such as a Twitter handle, then the metrics for that site will display zero. You can avoid seeing this by using the Metrics dropdown to de-select those metrics.

The Footer

The Footer contains a Refresh Now button, which will open a modal progress window displaying the progress of refreshing all of your sites. Keep in mind that using this too much may put you up against the daily limits of each API service. Additionally, there is an Export Data button that will generate a comma-seperated file (CSV) that makes it easy to use your data in another program. Clicking the button displays a modal that asks for a filename, and clicking the confirmation button generates a CSV file from the data displayed on the graph at the moment.

The Site Manager

SiteSearchStats - Site Manager

The Site Manager is where you can add or remove sites to track. You can track an unlimited amount of sites. Keep in mind, if you add a very large amount of sites, you may have to tweak your PHP settings to allow your cron script to run longer and with more memory.

Note: Sites do not have to have a Twitter Handle or Facebook ID, they are optional.

Sites Listing

Each site you are currently tracking is listed with its Name, Address, Twitter Handle, and Facebook ID. You have the option to delete a site if you no longer wish to track it. Deleting a site deletes ALL of its data.

Adding A Site

The form at the bottom of the Site Manager makes it easy to add a site to track. You must enter a unique name, a site address (without the http://), and an optional Twitter Handle and/or Facebook ID. After you enter a valid site, it is added to the Sites Listing and today's statistics are automatically fetched.

Not sure what your Facebook ID is? Use this site to easily figure out a page's numeric Facebook ID.

Other Screens

Tools

The Tools screen contains several diagnostic forms that will retrieve raw statistics or JSON queries for you. All output is loaded into the Output box.

About

This page contains credits and information about the libraries used in the application.

Help

This is the page you're viewing now!

Setting Up Your Cron Job

Local Service, or Remote

Most webhosts provide access to cron for automating tasks on your webserver. Check with your webhost if you're not sure. There are also a number of free cron services for remotely accessing a script, which will work well with SiteSearchStats.

Keep in mind that if you use DEMO mode, you will need to set up an additional cron job for the demo.php script in your base install folder to "clean" any sites added to your XML that you don't want to track indefinitely. For example, the demo script at iawix.com runs demo.php weekly to clean out any sites added during the previous week.

Change Your cron Password in config.php

Before you procede, edit the cron password declaration in includes/config.php:

define("SSS_CRONKEY", "password");

Recommended cron Settings

It's recommended that you update your statistics once a day via cron, at a time before you typically access your stats. For instance, this is the crontab command for using cURL to access the SiteSearchStats cronjob at 4AM every morning:

0 4 * * * curl http://yoursite.com/sitesearchstats/cron.php?key=password

Output

The cron.php script displays some debug information about each site's statistics, so if you'd like, you can elect to have your host send you this output every morning. Try using a pipe to the sendmail app on your host:

0 4 * * * curl http://yoursite.com/sitesearchstats/cron.php?key=password | /usr/sbin/sendmail me@myhost.com

The demo.php script includes a mail function that doesn't need a pipe to sendmail.

Further Support

If you're still in need of support, or you've spotted a bug, head to http://www.iawix.com/ to get in contact with the app developer.

Example XML Data

If you are having trouble with your sitesearchstats.xml file, you can place the online demo's XML in your includes/ folder to help stop errors on some hosts.