This project implements a proof-of-concept app events store backend and a statistics dashboard (react) to visualize user engagement.
The original motivation was to allow for interactive websites to record and analyze anonymous usage data without using cookies or tracking software. This article describes the approach in detail.
The current implementation is based on a simple LAMP (Linux/Apache/MySQL/PHP) architecture to make it deployable on any small or medium site. It would be easy though to replace the backend with a cloud based implementation to make it scale-up.
In order to log events, your website or app needs to submit events through HTTP GET
requests
to the backend API. This is typically done through ajax javascript functions within your website pages,
or through a suitable logging function in your app. Said functionality is not part of this package,
nevertheless examples of such scripts are provided below (see Logging).
The mysql or mariadb software must be installed on the server before hand.
The database and its user credentials are created as a first step.
This is typically done via the mysql admin console (e.g. phpMyAdmin
). The dbuser requires CREATE
, INSERT
and
SELECT
privileges.
The db details and access credentials are stored in an .ini
file in the following format
[database]
servername = localhost
username = <db_username>
password = <password>
dbname = <database_name>
log_table = <table_name_for_event_logging>
This file is stored typically in a directory outside the root path of the web server,
such as to block non-admin access to it. On my hosting service the root path for the site is
domains/mydomain.com/public_html/
and the .ini
files is located under
domains/mydomain.com/app-events.ini
WARNING This approach to storing db credentials is adequate for website event data but NOT SAFE for any sensitive data. Also, DO NOT share one and the same database (and dbuser) for logging and other data you may store as part of your website functionality.
Only one table is needed to record app events. The name of the table is defined in the database .ini
file. The table is created
as part of the installation.
The database requires about 75MB storage space for 1 million records (events).
The backend API is configured via public/config.php
.
<?php
mb_internal_encoding("UTF-8");
date_default_timezone_set ("Europe/Amsterdam");
setlocale(LC_TIME, 'en_NL');
// App wide constants
define('STATS_DB_DEV_INI', "../private/app-events.ini");
define('STATS_DB_PROD_INI', "../../app-events.ini");
define('STATS_SITE', "mydomain.com");
// Don't change beyond here
define('STATS_LOCK', true);
// Connect to the database
require_once('db.php');
$db = db_connect();
STATS_DB_PROD_INI
points to the locaion of the database .ini
file,
STATS_DB_DEV_INI
for the same file in a development environment.
The logging API consist of a single entry point, defined as follows
log.php?log=[event name: String]&r=[referral: String, optional]&l=[landing page: String, optional]
Referral and landing are optional.
Example 1 — A logging request signaling the homepage has been reached can be created with a script snippet like this
<script>
const ref = encodeURIComponent(document.referrer);
const landing = encodeURIComponent(window.location.href);
fetch(`app-events/log.php?log=homepage&r=${ref}&l=${landing}`);
</script>
provided the package has been deployed on a subdirectory /app-events/
under the website doc root.
No need to read any response, as the the log API returns nothing.
Example 2 — Signaling "contact me" button results
<script>
const contactEvent = () => {
// contact me
if(!confirm("Would you like to open your mail client?")){
fetch('app-events/log.php?log=contact-nok');
return false;
}
fetch('app-events/log.php?log=contact-ok');
}
</script>
...
<a href="mailto:me@mydomain.com?subject=Please contact me" onclick="contactEvent()">Contact me</a>
The minimum versions required for the backend are
MariaDB Server version: 10.3.24-MariaDB-cll-lve
PHP version: 5.5.38
Clone this repo.
Follow the database creation instructions and API config as described above.
Edit the file public/config.js
and replace <site_name>
with a name for your website or app (this name appears in the dashboard).
% cd <app-events-download-path>
% yarn install
% yarn build
Create a subdirectory app-events
under your public html website document root.
Upload the contents of the build/
subdirectory to app-events
Create the log table by calling up once https://yourwebsite.com/app-events/model.php
. If everything is configured properly,
you should get a success message as result. Upon success, the App Events manager is ready to work.
Update your html pages or app to start submitting events (see Logging above).
Open the dashboard https://yourwebsite.com/app-events/
on a web broswer
and check your results.
Have fun!