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.2, and is an open-source component of DocumentCloud.

Introduction | Installation | Usage | Change Log


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.


  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.


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":     "",
  "port":     "9187",
  "interval": 600,
  "endpoint": "http://www.example.com/internal/save_hits",
  "discard": false

Change Log

Changed the signal from USR1 (which is used by node for debugging) to USR2 and upgraded to http.request thanks to gka.

Initial release.

A DocumentCloud Project