Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

Moving documentation into a real web page.

  • Loading branch information...
commit 7affc8f7d18ee527099dea564d030a7e34ff90b3 1 parent a804dfd
@jashkenas jashkenas authored
Showing with 219 additions and 37 deletions.
  1. +2 −37 README
  2. +217 −0 index.html
View
39 README
@@ -15,40 +15,5 @@
It's useful when you want to keep track of page hits, but don't want to inject
something heavy like Google Analytics. It has no dependencies other than Node.
- To use Pixel Ping, you insert an image tag that records the hit, along with
- a unique key that is used to distinguish the hits. For example:
-
- <img src="/pixel.gif?key=13" alt="" />
-
- The key can be any string -- a document id, the url of the page, etc. You'll
- probably use a snippet of inline JavaScript to generate the key based on the
- URL of the page, and other relevant information. For an example of some
- JavaScript that generates the key, see the "with-tracking-js" branch.
-
- Pixel ping will store all of the keys and hits in memory, and periodically
- flush them to your application by making an HTTP request. You should make an
- endpoint on your application that can save results from JSON like this:
-
- {
- "/pages/about.html": 276,
- "/articles/policy.html": 324
- }
-
- The key being the key you passed to the image tag, and the value being the
- number of hits since the previous flush.
-
- To configure Pixel Ping, add a "config.json" file in its directory, or supply
- a path to the configuration file when starting it up. An example of the
- configuration looks like this:
-
- {
- "host": "127.0.0.1",
- "port": "9187",
- "interval": 600,
- "endpoint": "http://www.example.com/internal/save_hits"
- }
-
- Running "node lib/pixel-ping.js path/to/config.json" will start up the pixel
- server on 127.0.0.1:9187, and every ten minutes (600 seconds), it will flush
- the hits to the provided endpoint.
-
+ For installation and usage instructions, see:
+ http://documentcloud.github.com/pixel-ping
View
217 index.html
@@ -0,0 +1,217 @@
+<!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: #55cccc;
+ color: #333300;
+ }
+ a:active, a:hover {
+ color: #000;
+ background: #44dddd;
+ }
+ 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>Pixel Ping is currently at <b>version 0.1.1</b>.</p>
+
+ <p>
+ <i>Pixel Ping is an open-source component of <a href="http://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 from the client-side, insert an image tag into the page
+ that records your hit, 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.
+ </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.1</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>
Please sign in to comment.
Something went wrong with that request. Please try again.