Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Put all your site visitors on a map
JavaScript CoffeeScript Other
Branch: master

README.md

Geosockets

Geosockets is a Node.js webserver and javascript browser client for rendering website visitors on a map in realtime using WebSockets and the browser's Geolocation API.

See the demo app at geosockets.herokuapp.com and the Heroku WebSocket Beta announcement at blog.heroku.com/archives/2013/10/8/websockets-public-beta.

The Client

client.coffee is written as a node app that uses Coffeeify (the red-headed step-child of browserify) and Grunt to transpile the source into a single browser-ready javascript file.

When the client is first run in the browser, a UUID token is generated and stored in a cookie which is passed to the server in the headers of each WebSocket message. This gives the server a consistent way to identify each user.

The client uses the browser's geolocation API and the geolocation-stream node module to determine the user's physical location, continually listening for location updates in realtime. Once the WebSocket connection is established, the client broadcasts its location to the server:

{
  uuid: '6e381608-2e63-4e40-bf6c-31754935a5c2',
  url: 'https://blog.heroku.com/archives/2013/10/3/websockets-public-beta',
  latitude: 37.7521248,
  longitude: -122.42365649999999
}

The client then listens for messages from the server, rendering and removing markers from the map as site visitors come and go.

The Server

server.coffee is a node app powered by express 3, node's native http module, and the einaros/ws WebSocket implementation. Express is used to serve the static frontend in /public.

The server was designed with horizontal scalability in mind. The shared location dataset is stored in a redis datastore and each web dyno connects to this shared resource to pull the complete list of pins to place on the map. Clients viewing the map each establish their own WebSocket connection to any one of the backend web dynos and receive real-time updates as locations are added and removed from the redis datastore.

When the server receives a message from a client, it adds the client's location data to the Redis store (or updates if it's already present), using the combined client's URL/UUID pair as the Redis key:

@redis.setex "#{user.url}---#{user.uuid}", @ttl, JSON.stringify(user)

The server then fetches all keys from Redis that match that URL and broadcasts the update to all connected clients at that same URL.

Embedding the Javascript Client on Your Site

The Geosockets JavasScript client can be used on any website:

<link rel="stylesheet" type="text/css" href="https://geosockets.herokuapp.com/styles.css">
<script src="https://geosockets.herokuapp.com/client.js"></script>
<script>window.geosocket = new Geosocket("wss://geosockets.herokuapp.com");</script>
<div id="geosockets"></div>

Use CSS to configure the size and position of the map container:

#geosockets {
  width: 100%;
  height: 100%;
}

Running Geosockets Locally

If you're new to Heroku or Node.js development, you'll need to install a few things first:

  1. Heroku Toolbelt, which gives you git, foreman, and the heroku command-line interface.
  2. Node.js
  3. Redis. If you're using homebrew, install with brew install redis

Clone the repo and install npm dependencies:

git clone https://github.com/heroku-examples/geosockets.git
cd geosockets
npm install
npm install -g grunt-cli

The foreman Procfile defines the processes required to run the app. Fire up redis, a grunt watcher, and the node webserver at localhost:5000/?debug:

foreman start

Debugging

The client uses a custom logging function that only logs messages to the console if a debug query param is present in the URL, e.g. localhost:5000/?debug. This allows you to view client behavior in production without exposing your site visitors to debugging data.

Testing

Basic integration testing is done with CasperJS, a navigation scripting & testing utility for PhantomJS. Casper is integrated into the app using the grunt-casper plugin, and run with foreman. Each time you make a change to your client, the casper tests are run automatically.

Deploying Geosockets to Heroku

heroku create my-geosockets-app
heroku labs:enable websockets
heroku addons:add openredis:micro # $10/month
git push heroku master
heroku open
Something went wrong with that request. Please try again.