Permalink
Switch branches/tags
Nothing to show
Find file
Fetching contributors…
Cannot retrieve contributors at this time
222 lines (199 sloc) 6.3 KB
<!DOCTYPE HTML>
<html>
<head>
<meta http-equiv="content-type" content="text/html;charset=UTF-8" />
<meta http-equiv="X-UA-Compatible" content="chrome=1">
<title>Pixel Ping</title>
<style>
body {
font-size: 16px;
line-height: 24px;
background: #eff7ff;
color: #022;
font-family: Arial;
font-family: "Palatino Linotype", "Book Antiqua", Palatino, FreeSerif, serif;
}
div.container {
width: 720px;
margin: 50px 0 50px 50px;
}
p, li {
margin: 16px 0 16px 0;
width: 550px;
}
p.break {
margin-top: 35px;
}
a, a:visited {
padding: 0 2px;
text-decoration: none;
background: #77dddd;
color: #003333;
}
a:active, a:hover {
color: #000;
background: #00cccc;
}
h1, h2, h3, h4, h5, h6 {
margin-top: 40px;
}
b.header {
font-size: 18px;
}
span.alias {
font-size: 14px;
font-style: italic;
margin-left: 20px;
}
table {
margin: 16px 0; padding: 0;
}
tr, td {
margin: 0; padding: 0;
}
td {
padding: 9px 15px 9px 0;
}
td.definition {
line-height: 18px;
font-size: 14px;
}
code, pre, tt {
font-family: Monaco, Consolas, "Lucida Console", monospace;
font-size: 12px;
line-height: 18px;
color: #444;
}
code {
margin-left: 20px;
}
pre {
font-size: 12px;
padding: 2px 0 2px 12px;
border-left: 6px solid #55aaaa;
margin: 0px 0 10px;
}
li pre {
padding: 0;
border-left: 0;
margin: 6px 0 6px 0;
}
#diagram {
margin: 20px 0 0 0;
}
</style>
</head>
<body>
<div class="container">
<h1>Pixel Ping <sub style="font-size:150%;">&#9732;</sub></h1>
<p>
<a href="http://github.com/documentcloud/pixel-ping/">Pixel Ping</a>
is a minimalist pixel-tracker written in
<a href="http://coffeescript.org">CoffeeScript</a> for
<a href="http://nodejs.org">Node.js</a>.
</p>
<p>
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.
</p>
<p>
<a href="docs/pixel-ping.html">The complete annotated source code</a>
is also available.
</p>
<p>
<i>Pixel Ping is currently at <b>version 0.1.2</b>, and is an open-source
component of <a href="http://www.documentcloud.org/">DocumentCloud</a>.</i>
</p>
<p>
<a href="#introduction">Introduction</a> |
<a href="#installation">Installation</a> |
<a href="#usage">Usage</a> |
<a href="#changes">Change Log</a>
</p>
<h2 id="introduction">Introduction</h2>
<p>
Embeddable content that gets a lot of page views is often cached and served
statically &mdash; 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.
</p>
<h2 id="installation">Installation</h2>
<ol>
<li>
Pixel Ping depends on <b>Node.js</b> and the <b>Node Package Manager</b>
(npm). If you don't already have these installed, grab the latest. Node
releases can be found on the <a href="http://www.nodejs.org/#download">download page</a>.
NPM can be installed with a script:<br />
<tt>curl http://npmjs.org/install.sh | sudo sh</tt>
</li>
<li>
Install Pixel Ping via NPM:<br />
<tt>sudo npm install pixel-ping</tt><br />
As always, leave off "sudo" if you don't need it.
</li>
</ol>
<h2 id="usage">Usage</h2>
<p>
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:
</p>
<pre>
&lt;img src="/pixel.gif?key=[KEY]" alt="" /&gt;</pre>
<p>
The key can be any string &mdash; 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:
</p>
<pre>
{
"/pages/about.html": 276,
"/articles/policy.html": 324
}</pre>
<p>
... 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
<tt>SIGUSR1</tt> signal to the Pixel Ping process.
</p>
<p>
Installing Pixel Ping gives you the <tt>pixel-ping</tt> command. To launch it,
you pass the path to your configuration file:
</p>
<pre>
pixel-ping path/to/config.json</pre>
<p>
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.
</p>
<pre>
{
"host": "127.0.0.1",
"port": "9187",
"interval": 600,
"endpoint": "http://www.example.com/internal/save_hits"
}</pre>
<h2 id="changes">Change Log</h2>
<p>
<b class="header">0.1.2</b><br />
Initial release.
</p>
<p>
<br />
<a href="http://documentcloud.org/" title="A DocumentCloud Project" style="background:none;">
<img src="http://jashkenas.s3.amazonaws.com/images/a_documentcloud_project.png" alt="A DocumentCloud Project" style="position:relative;left:-10px;" />
</a>
</p>
</div>
</body>
</html>