Permalink
Find file
Fetching contributors…
Cannot retrieve contributors at this time
266 lines (225 sloc) 7 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 https://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>SIGUSR2</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",
"discard": false
}</pre>
<p>
If the endpoint is hosted on an https server, you must specify the port number after the domain name. For example:
</p>
<pre>
{
"endpoint": "https://www.example.com:443/internal/save_hits",
}
</pre>
<p>
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.
</p>
<pre>
{
"sslkey" : "/path/to/privkey.pem",
"sslcert" : "/path/to/cert.pem",
"sslca" : "/path/to/chain.pem",
}
</pre>
<h2 id="changes">Change Log</h2>
<p>
<b class="header">0.1.3</b><br /> Changed the signal from USR1 (which is used by node for debugging) to USR2 and upgraded
to <tt>http.request</tt> thanks to
<a href="https://github.com/gka">gka</a>.
</p>
<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>