Tracking Script Installation

General Considerations

The script should be installed in a publicly accessible location on your server. You can set the QR Code location to a path like: http://yourdomain.com/campaign or http://yourdomain.com/campaign/tracking.php. In the former case the name of the script should be the default name expected by your HTTP server (for Apache usually index.php, for IIS usually default.php) and in the latter the name of the file can be set as desired because it is contained in the QR code URL.

The tracking script logs the visits data in CSV files in the local filesystem. This implies that the HTTP server must have write permissions to the location where the files will be saved.
The system also logs the attempts to retrieve the visits data with the incorrect Secret Key.

Script Modifications

The provided tracking script has its code clearly displayed and not obfuscated so it is editable by the end user. A few variables within the script are user editable in case there is need to change the default values to tune the script to your server environment. Soon we will provide an online editor/configurator for setting these variables.Editable variables:

  • File_path (stirng) - the path where the CSV data file(s) will be saved
  • Offending_ips_file_path (string) - the path where any offending IP will be stored
  • Delete_retrieved_data (bool) - shall the already retrieved by the tracking system data be deleted or preserved

Customer modifications of these variables are supported. Any other modifications of the tracking script are not supported but we do provide custom development and configuration services when this is needed.

Tracking Data Files

The system can be configured to either delete the data that was already retrieved by the tracking system or to archive it. In the former case the only data file at one time present on the server will be 'self_hosted_stats_RANDOMSTRING.cvs' that contains new visits that are not yet retrieved (the tracking system polls the script every 5 minutes) and in the latter the files containing the retrieved data will be renamed to 'self_hosted_stats_RANDOMSTRING.cvs_1', 'self_hosted_stats_RANDOMSTRING.cvs_2' etc. This means that every time the tracking system polls the script a new file will be create; as this means a lot of files by default the script deletes the old data. In case you need the tracking data for your own purposes this behavior can be changed by setting the delete_retrieved_data variable to FALSE.
The default path for the visits data file is the current directory of the script and the default file name is 'self_hosted_stats_RANDOMSTRING.cvs'. The default path for logging the offending IPs is the current directory of the script and the default file name is 'self_hosted_offending_ips_RANDOMSTRING.txt'.

Integration with Third Party Software

An important technical detail is that once the visits are retrieved by the system they can not be retrieved again by polling the script. This means that if you are developing a custom solution that will use the data from the tracking script you should not poll the script using the HTTP protocol and the Secret Key as this will trigger data deletion or archiving, but instead enable the data archiving (see the "Tracking data files" section) and use the archived files to retrieve the data.
Please note that if the tracking script is regenerated (because of Secret Key or Content change) the variables will be reset and new names/paths for the CSV files will be set and you will need to adjust accordingly your software that uses these files. This issue will be resolved when the online editor/configurator for the tracking script is introduced - there will be an option to preserve these settings.

Security Considerations

The data retrieval by polling the tracking script is protected by a Secret Key so that the script will provide the data only to authorized parties (like the Tracking System). There is still a way for an unauthorized person to access the raw visits data by simply issuing a direct HTTP request like "http://yourdomain.com/campaign/self_hosted_stats.csv" (assuming the tracking script is accessible at http://yourdomain.com/campaign/). To prevent this there are three options (ordered by most secure to less secure):

  • Change the locations of the CSV files to a location that is not publicly accessible. You can do that by changing the value of the file_path variable.
  • If your server supports .htaccess files you can upload a .htaccess file (in the same location where the tracking script is installed) that prevents access to any .csv file (and leave the default path for the CSV). Here you can download a .htaccess file that may (or may not!) work on your server
  • To install the script in a directory and use the default name expected by your HTTP server (index.php for Apache and default.php for IIS for example). This way the script will prevent files listing and the CSV files will be protected by the fact of their complex name (self_hosted_data_SOMERANDOMSTRING.csv) which would be hard to guess (but not impossible after many tries so watch your logfiles!). Better combine this with a .htaccess file to explicitly prevent the access to the .csv files.

We can provide assistance in securing your installation of the self hosted tracking script - you can reach us here.

PHP Specifics

The tracking script for php requires PHP version 4.3 or higher. If your server uses a different extension for the php files other than the .php please rename the downloaded script accordingly. If you customize the tracking script and run into errors you can enable the error reporting by changing the line "error_reporting(0)" to "error_reporting(E_ALL)".

.NET Specifics

The .NET tracking script is configured to save the files under the "files" sub-directory under the current working directory. The script must have write permissions in this directory as well for security reasons it should be denied to list and access the files in this directory or otherwise the script can be edited  (C# source) so that the files are placed outside the web server tree.