Pixel Ping _☄

Pixel Ping is a minimalist pixel-tracker written in CoffeeScript for Node.js.

If you provide embeddable applications or HTML widgets for third-party sites, are serving them statically, would like to keep track of specific usage information, and don't want to inject something heavy like Google Analytics, perhaps Pixel Ping can help.

The complete annotated source code is also available.

Pixel Ping is currently at version 0.1.6, and is an open-source component of DocumentCloud.

Introduction | Installation | Usage | Change Log

Introduction

Embeddable content that gets a lot of page views is often cached and served statically — especially for third-party sites where traffic is unpredictable. It's not appropriate to serve a dynamic request for every hit, invoking a heavy web stack and burying the database under lots of tiny writes. Pixel Ping builds up an in-memory hash of unique keys to hits, where the keys are arbitrary values generated by your embedded content. At a configurable interval, Pixel Ping flushes the keys and hits to your web application via a REST request, and your application can then analyze and store the data.

Installation

1. Pixel Ping depends on Node.js and the Node Package Manager (npm). If you don't already have these installed, grab the latest. Node releases can be found on the download page. NPM can be installed with a script:
   curl https://npmjs.org/install.sh | sudo sh
2. Install Pixel Ping via NPM:
   sudo npm install pixel-ping
   As always, leave off "sudo" if you don't need it.

Usage

To use Pixel Ping in your embedded content, insert an image tag into the page, along with the unique key that distinguishes hits for aggregation:

<img src="/pixel.gif?key=[KEY]" alt="" />

The key can be any string — a model id, the URL of the page, the embed options, etc. You'll probably either use your server-side template or a snippet of inline JavaScript to generate the key. When Pixel Ping flushes the hits to your application, you'll receive a JSON hash of hits that looks like this:

{
  "/pages/about.html":      276,
  "/articles/policy.html":  324
}

... where the key is the key you passed to the image tag, and the value is the number of hits since the previous flush. To force a flush, send a SIGUSR2 signal to the Pixel Ping process.

Installing Pixel Ping gives you the pixel-ping command. To launch it, you pass the path to your configuration file:

pixel-ping path/to/config.json

In the configuration file, specify the host and port you'd like Pixel Ping to bind to, as well as the interval (in seconds) at which to flush the hits, and the URL endpoint where your application accepts the aggregated hits and keys. For security, you may specify an optional "secret" string, which will be passed along with each flush from Pixel Ping to your internal API.

{
  "host":     "127.0.0.1",
  "port":     "9187",
  "interval": 600,
  "endpoint": "http://www.example.com/internal/save_hits",
  "discard": false
}

If the endpoint is hosted on an https server, you must specify the port number after the domain name. For example:

{
  "endpoint": "https://www.example.com:443/internal/save_hits",
}
    

In addition, a user can setup SSL credentials to start the server under HTTPS. The SSL key and cert paths are required for HTTPS. The SSL chain path is optional.

{
  "sslkey" : "/path/to/privkey.pem",
  "sslcert" : "/path/to/cert.pem",
  "sslca" : "/path/to/chain.pem",
}
    

Change Log

0.1.6 March 25, 2019
Fixed a bug in HTTPS support, where you previously would have to explicitly specify port 443, thanks to Daniel Beardsley.

0.1.5 March 25, 2019
Fixed a data loss bug, where hits that were recorded during a flush would be discarded, thanks to Daniel Beardsley.

0.1.4 August 22, 2017
Added HTTPS support, for both the pixel server and the endpoint flush, thanks to Maxwell Francisco.

0.1.3 May 29, 2014
Changed the signal from USR1 (which is used by node for debugging) to USR2 and upgraded to http.request thanks to Jeff Larson and Gregor Aisch.

0.1.2 September 8, 2010
Initial release.